Errors

Every error code the API returns, what it means and what to do next.

Error format

Error bodies are { "code": "…", "error": "…" }. Branch on code, not on the message. Retry only when the outcome is known; keep the Idempotency-Key for an uncertain network outcome. Responses include an x-request-id header to quote in support requests.

Error codes

HTTP	Code	Meaning and action
`401`	`AUTH_REQUIRED`	Missing or invalid API key or session.
`403`	`INSUFFICIENT_SCOPE`	The API key lacks the scope this endpoint needs.
`403`	`PERMISSION_DENIED`	This credential cannot perform the operation.
`429`	`API_KEY_RATE_LIMITED`	The API key's rate limit was reached. Honor Retry-After.
`429`	`API_KEY_USAGE_EXCEEDED`	The API key reached its usage limit. Create a new key.
`400`	`INVALID_REQUEST`	The body is not a JSON object or a required value is missing.
`400`	`INVALID_IDEMPOTENCY_KEY`	Idempotency-Key must be 1–128 printable ASCII characters.
`400`	`INVALID_MODEL_INPUT`	input does not match the model schema (unknown field, missing required field, or invalid value).
`400 / 413`	`INPUT_TOO_LARGE`	The request body is larger than 256 KB. Upload media first and send a media reference.
`404`	`REQUEST_NOT_FOUND`	No chat request with this ID belongs to your account.
`404`	`MODEL_NOT_FOUND`	No model has this slug.
`404`	`JOB_NOT_FOUND`	No task with this ID belongs to your account.
`409`	`IDEMPOTENCY_CONFLICT`	This Idempotency-Key was used with different input. Use a new key for a new request.
`409`	`PRICE_CHANGED`	The price differs from expectedPriceMicros. Fetch the price and confirm again.
`409`	`MODEL_PRICE_UNAVAILABLE`	No price is configured for this model yet, so it cannot run.
`409`	`PAYMENT_REVIEW_REQUIRED`	A refund left an uncovered balance. Contact support or cover the balance before submitting tasks.
`409`	`INSUFFICIENT_CREDITS`	Available credits do not cover the task price.
`429`	`RATE_LIMITED`	Too many task submissions per minute. Retry later.
`429`	`CONCURRENCY_LIMITED`	Too many unfinished tasks. Wait for one to finish.
`503`	`EXECUTION_UNAVAILABLE`	Execution is not configured for this model right now.
`429`	`UPSTREAM_RATE_LIMITED`	The model provider is rate limiting chat requests. Retry with backoff; nothing was charged.
`502`	`UPSTREAM_ERROR`	The model provider failed the chat request. Nothing was charged; retry later.
`503`	`PLATFORM_BUDGET_EXCEEDED`	This model is temporarily unavailable. Try again later.
`503`	`EXECUTION_TEMPORARILY_UNAVAILABLE`	Execution is temporarily unavailable. Retry with the same Idempotency-Key.
`503`	`AUTH_UNAVAILABLE`	Authentication is temporarily unavailable. Retry later.
`503`	`API_UNAVAILABLE`	The API is temporarily unavailable. Retry later.