Error codes

Errors are returned via HTTP status codes and the detail field.

Status codes#

Code	Name	Description
400	Bad Request	Invalid request. Unsupported model ID, a disallowed model/tier (key scope restriction), a parameter out of range, and so on.
401	Unauthorized	Missing API key, invalid key, expired key, or deleted user.
402	Payment Required	Insufficient credits (insufficient_credits): top up and retry. Key monthly budget exceeded (monthly_budget_exceeded): adjust the key's budget in Dashboard → API Keys.
403	Forbidden	Resource access denied. Occurs with a disabled key or access to a model outside the allowed set.
429	Too Many Requests	Rate limit exceeded. Default 60 RPM per API key. Wait a moment and try again.
502	Bad Gateway	Upstream provider error. The request still failed after automatic retries and fallback. No credits are charged.

Structured errors#

Billing/consent-related errors include a machine-readable code string in detail.error.

402 — insufficient_credits

{
  "detail": {
    "error": "insufficient_credits",
    "message": "Insufficient available credits: ₩120 < ₩540"
  }
}

403 — forbidden

{
  "detail": {
    "error": "forbidden",
    "message": "You do not have access to this resource"
  }
}

Retry guidance#

Retry 429 and 502 with exponential backoff. The server already retries provider calls twice, so we recommend a client retry interval of at least 1 second. For 4xx, retrying produces the same result until you fix the request.