Errors

Errors use this shape:

{
  "error": {
    "code": "invalid_payload",
    "message": "The image API payload is invalid."
  },
  "request_id": "req_abc123"
}

Common errors

HTTP	Code	Meaning
`400`	`invalid_payload`	Request JSON or fields are invalid.
`400`	`invalid_idempotency_key`	Missing or invalid `Idempotency-Key`.
`400`	`invalid_query`	Job list query parameters are invalid.
`400`	`invalid_job_id`	Job id is not a valid UUID.
`400`	`too_many_results`	Request would create more than the allowed result count.
`400`	`invalid_webhook_url`	Webhook URL is unsafe or not HTTPS.
`401`	`invalid_api_key`	API key is missing, invalid, revoked, or expired.
`401`	`api_key_inactive`	API key exists but is inactive.
`402`	`insufficient_api_credits`	Not enough paid credits are available.
`403`	`api_access_not_enabled`	Live API access is not available for the account.
`403`	`payment_risk_restricted`	Wallet is under payment review.
`409`	`idempotency_conflict`	Same key was reused with a different body.
`404`	`job_not_found`	Job does not exist for this API key environment.
`429`	`rate_limit_exceeded`	Request limit was exceeded.
`429`	`too_many_active_jobs`	Account or API key has too many queued or processing jobs.
`429`	`too_many_pending_results`	Account has too many results waiting in this capacity group.
`503`	`capacity_unavailable`	The tool queue is disabled, full, or older than its load-shedding threshold.
`503`	`tools_unavailable`	Tools catalog is temporarily unavailable.

Situation	Retry?	Use same idempotency key?
Network timeout while creating a job	Yes	Yes
`idempotency_conflict`	No	No
`rate_limit_exceeded`	Later	Same body/key if retrying same create request
`too_many_active_jobs`	After `Retry-After`	Same body/key
`too_many_pending_results`	After `Retry-After`	Same body/key
`capacity_unavailable`	After `Retry-After`	Same body/key
Result-level provider failure	Later	No, create a new job for retry