Errors

Any response outside the 2xx range looks like this:

{
  "error": {
    "code": "payment_required",
    "message": "Insufficient credits for this generation.",
    "trace_id": "c3746d5302dc4be6b2e8fa99fa762a8c",
    "details": []
  }
}

details appears only on validation errors and lists each offending field. Quote trace_id when you write to support; it finds the exact request.

Codes

HTTP	`code`	What to do
401	`unauthenticated`, `invalid_api_key`	The key is missing, revoked, expired or wrong. Create a new one in Settings → Team.
402	`payment_required`	Not enough credits. Top up, then retry.
403	`forbidden`, `api_key_scope`	Keys only call `/v1`; or your plan cannot use this model.
404	`not_found`	Wrong id, or the API is not enabled for this environment.
409	`conflict`	An `Idempotency-Key` was reused with a different body. Use a new key.
422	`validation_error`	A field is missing, unknown or out of range. See `details`.
429	`rate_limited`	Wait the number of seconds in `Retry-After`, then retry.
5xx	`internal_error`	Retry with backoff; include `trace_id` if it persists.

Generation failures are not HTTP errors

A generation that was accepted but did not finish is a 200 with "status": "failed" and an error object on the generation itself. Its code is one of rate_limited, timeout, safety, invalid_voice, invalid_request, billing_or_access, provider_auth, provider_unavailable, provider_error. safety and invalid_request need a different prompt or input; the others are worth one retry.

Start here

Using the API

Choosing a model

Image models

Video models

Audio models

Agents and MCP

Codes

Generation failures are not HTTP errors

​Codes

​Generation failures are not HTTP errors

Codes

Generation failures are not HTTP errors