Developer API

Errors and Billing

Most long-running jobs return queued ids immediately. Billing and budget responses include credit fields so clients can show clear user-facing decisions.

#HTTP errors

Clients should branch on status code and error code, then show user-facing billing or retry decisions.

CodeDescription

401

Missing, expired, or invalid bearer token.

402

Insufficient credits, budget exceeded, or premium approval required.

403

The API key is valid but does not include the scope required for the endpoint.

404

Requested generation, repurpose task, user, or account was not found.

409

The device code has already been used or the request conflicts with current state.

429

The API key or organization exceeded the current request limit.

502

The gateway could not reach or read an upstream provider.

503

No configured provider route is available or the upstream provider failed.

500

Queue, database, provider, or internal processing failure.

#Error response shapes

Most endpoints return a structured error body with code and message. AI Gateway chat routes return OpenAI-compatible error.type, error.code, and error.message. Some legacy media handlers still return a string error body.

Example

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits"
  }
}

{
  "error": {
    "type": "provider_unavailable",
    "code": "provider_unavailable",
    "message": "No configured provider route completed the request"
  }
}