API

Errors

The error format, what each code means and how to handle it.

Failed requests return a non-200 HTTP status and a body in this format:

Error format

{
  "error": {
    "message": "Insufficient credits. Please top up and try again.",
    "type": "relay_error",
    "code": "insufficient_quota",
    "request_id": "req_8c1f02…"
  }
}

code	HTTP	Meaning	What to do
`invalid_api_key`	401	The key is invalid, expired or disabled	Check the key under API Keys in the console
`insufficient_quota`	402	Account credits or this key’s limit are used up	Add credits or raise the key’s spending limit
`rate_limited`	429	Too many requests	Lower concurrency and retry after a few seconds
`invalid_request`	400	A request parameter is wrong	Read the message and check the request body
`context_length_exceeded`	400	Input exceeds the model’s context window	Shorten the input or use a model with a longer context
`content_filtered`	400	The request was blocked by a content policy	Change the content. Uncensored models rarely trigger this.
`model_unavailable`	404 / 503	Unknown model ID, or the model is temporarily unavailable	Check the model ID, retry later or switch models
`service_unavailable`	503 / 504	The service is temporarily unavailable	Retry later. Contact support if it persists.

Retries

Retry only on 429, 503 and 504, with exponential backoff (for example 1 s, 2 s, 4 s) and at most three attempts. Retrying 400, 401 or 402 will not help until the cause is fixed.

request_id

Every response carries an x-request-id header, and error bodies include it too. Quote it when you contact support so the exact request can be found.