Errors

HTTP status codes and the stable error codes you branch on.

Errors always use the standard envelope — a stable code plus a human message:

{
  "error": {
    "code": "insufficient_credits",
    "message": "You need 3 credits but have 1 remaining"
  }
}

Branch on error.code. Treat message as display text only.

HTTP status codes

Code	Meaning
`200`	Success (reads, and terminal/replayed mutations)
`201`	A new resource, quote, or async operation was created
`202`	The mutation outcome is being reconciled — retry the exact request with the same key
`400`	Validation error or invalid URL
`401`	Missing or invalid API key
`402`	Insufficient credits
`403`	Access denied (e.g. a voice owned by another user, or no active plan)
`404`	Resource not found
`409`	Resource-state or idempotency conflict — don’t retry with a changed body under the same key
`413`	Request payload too large
`429`	Rate limit exceeded, or too many concurrent generations
`500`	Internal error (billing, database, or engine)
`503`	A required service or operation is held/unavailable — check the error code before retrying

Code	Status	Description
`missing_api_key`	401	No `Authorization` header
`invalid_api_key`	401	Key not found or revoked
`expired_api_key`	401	Key passed its expiration date
`plan_required`	403	No active Creator or Studio plan
`validation_error`	400	Invalid request input (details in `message`)
`invalid_filter`	400	Invalid, empty, or repeated list filter
`invalid_url`	400	URL failed SSRF validation
`invalid_cursor`	400	Malformed pagination cursor
`insufficient_credits`	402	Not enough credits (includes `balance` and `required`)
`access_denied`	403	Resource belongs to another user
`not_found`	404	Resource doesn’t exist or isn’t yours
`idempotency_conflict`	409	The key is bound to a different request
`rate_limit_exceeded`	429	Too many requests (see `Retry-After`)
`too_many_active`	429	Max 3 concurrent generations
`billing_error`	500	Credit system failure
`creation_failed`	500	Database write failure
`engine_error`	500	Generation engine failure

While paid intake and other features are held, these 503 codes are expected:

Code	Meaning
`PAID_INTAKE_HELD`	Paid create routes are held behind a deployment flag
`webhook_delivery_unavailable`	A `webhook_url` was supplied; customer webhooks are disabled
`character_deletion_unavailable`	Character deletion is held
`generation_deletion_unavailable`	Generation deletion is held