Errors & status codes

The API uses standard HTTP status codes and a consistent error body for failures.

HTTP status codes

Code	Meaning	Typical cause
200	OK	Request succeeded.
400	Bad Request	Invalid body, missing required field, or malformed parameters.
401	Unauthorized	Missing or invalid API key.
402	Payment Required	Insufficient account balance.
403	Forbidden	Not allowed (e.g. wrong host or endpoint).
404	Not Found	Model, job, or resource ID not found.
429	Too Many Requests	Rate limit exceeded.
500	Internal Server Error	Server or upstream error; retry with backoff.
502	Bad Gateway	Upstream service error.
503	Service Unavailable	Service temporarily unavailable.

Error responses are JSON with at least:

Field	Type	Description
`error`	string	Short code or description (e.g. `invalid_api_key`, `Insufficient balance`).
`message`	string	Optional; human-readable details.

For 429, the response may include:

Field	Type	Description
`retryAfter`	number	Suggested seconds to wait before retrying.

Example:

{
  "error": "Insufficient balance. Please add funds to your account."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please slow down.",
  "retryAfter": 60
}

Scenario	Status	Suggested action
Wrong or missing API key	401	Check `Authorization: Bearer sk_...` and key in dashboard.
Out of balance	402	Add funds and retry; show “Add funds” in UI.
Invalid model ID	404	Use a model from the models list.
Rate limited	429	Back off; use `retryAfter` if present.
Server error	500, 502, 503	Retry with exponential backoff; contact support if persistent.

Parse the body — Read the JSON error (and message) and display or log it.
Map status to UX — 401 → “Sign in or check API key”; 402 → “Add funds”; 429 → “Too many requests; retry in X seconds.”
Retries — Retry only on 429, 500, 502, 503; use backoff and optional retryAfter. Do not retry 400, 401, 402, 404 without fixing the request or account.
Idempotency — For non-idempotent operations, use idempotency keys if the API supports them to avoid duplicate charges on retry.