API docs · Reliability

Error codes

The common error body and every error code.

All errors share one structure (see the example on the right). The table below lists the error.code values the API can return and their HTTP statuses; one status can map to several error codes:

HTTP	code	When	Retryable	What to do
400	`invalid_request`	Malformed JSON, Content-Type is not application/json, or Idempotency-Key is missing or too long; a request body over 1 MB returns 413	No	Fix the request and resend
401	`invalid_api_key`	Key does not exist, or is revoked, expired or disabled	No	Check the key status in the console
401	`unauthenticated`	Console session is missing or expired	No	Sign in again
402	`quota_exceeded`	Not enough available quota in the account; the reserve ceiling exceeds max_budget (param is max_budget); or asset storage is full	No	Top up, adjust max_budget or clean up assets, then retry
402	`key_limit_exceeded`	The key's total or daily limit is insufficient	No	Raise the key limit, then retry
403	`permission_denied`	Key lacks the scope, the model is not in the key's allowlist, or the model is not enabled for the account	No	Grant the key the permission in the console, or contact our operations team to enable the model
403	`csrf_failed`	Console request has a missing or expired CSRF token	No	Refresh the page and try again
403	`account_suspended`	The account is suspended	No	Contact our operations team
404	`not_found`	Resource does not exist or does not belong to you	No	Check that the ID is correct
404	`not_available`	Feature is only offered on the Global site and is not available on this site	No	Use the site that offers it
403	`terms_required`	Latest top-up terms not yet accepted	No	Read and accept the top-up terms, then retry
409	`idempotency_conflict`	Same idempotency key with a different request body	No	Use a new idempotency key for a new request
409	`conflict`	Resource state conflict	No	Fetch the latest state, then try again
409	`group_not_empty`	The group still contains assets	No	Move or delete its assets first
422	`invalid_parameter`	Invalid parameter or unsupported combination (never silently dropped)	No	Fix the parameters against the model capabilities
422	`asset_not_ready`	Asset is still processing	Yes	Retry once its status is available
422	`authorization_required`	Real-person asset lacks a valid authorization	No	Complete real-person authorization, then retry
429	`rate_limited`	Key RPM exceeded, or the account's / key's concurrency limit reached	Yes	Back off per Retry-After, then retry
500	`internal_error`	Internal platform error	Yes	Retry with the same idempotency key

When retryable is true, retry with backoff. Retries of task creation must use the same Idempotency-Key.

Failures that occur only after a task is accepted (for example, no processing route is currently available) are not returned as API errors; they appear in the task's error.code instead. See task failure codes.

Error response

HTTP/1.1 422 Unprocessable Entity
X-Request-Id: req_xxx

{
  "error": {
    "code": "asset_not_ready",
    "message": "Asset asset_xxx is still processing. Retry once its status is available.",
    "param": "inputs[0].asset_id",
    "retryable": true,
    "request_id": "req_xxx"
  }
}