Errors

The API uses conventional HTTP status codes to signal success and failure.

Status	When
401	Missing, invalid, or inactive API key.
402	Insufficient funds to reserve the job’s price.
403	API key lacks permission for the requested model.
404	GET /jobs/{job_id} for an unknown id or a job owned by another account.
422	Validation failure — too many input images or oversized input (base64).
502	Upstream storage failure while ingesting inputs.
503	The project or the requested model is paused — try again later.

Handling tips

401 — Authentication

Verify the Authorization: Bearer <key> header and that the key is active. See Authentication.

402 — Insufficient funds

Check GET /balance. The available amount must cover the job's reserved price.

403 — Model permission

The key isn't scoped for the requested model. Grant access in the web panel or use a different key.

422 — Validation

Common causes: too many input_images_urls entries, total input size over 200 MB, or an aspect_ratio the model doesn't support. An input URL that can't be fetched does not return 422 — the job is accepted (202) and later transitions to failed with error code missing_input_images.

503 — Paused

Transient — the project or model is paused. Retry later, ideally with the same Idempotency-Key.