Errors and retries

Error codes returned by the Ertas AI Gateway, what each one means, which ones to retry, and how to use the Retry-After header.

Ask AI about this page

On this page

Errors from the gateway itself use this shape:

{ "error": { "type": "ertas", "code": "credits_exhausted", "message": "You're out of Ertas credits. Top up on the Billing page." } }

Errors from the model, such as a context that is too long, keep the model server's status and come back in the OpenAI error shape.

Error codes

Status	Code	Meaning	What to do
401	`missing_token`	No API key was sent	Send `Authorization: Bearer $ERTAS_API_KEY`
401	`invalid_token`	The key isn't recognised	Check the value and the base URL
401	`ertas_token_revoked` / `ertas_token_expired`	The key was revoked or expired	Create a new key
400	`invalid_json`	The request body isn't valid JSON	Fix the body
400	`invalid_model` / `unknown_model`	`model` is missing or isn't on your endpoint	Copy the ID from the Models page
400	`unsupported_for_provider`	A Responses API feature that needs stored responses, such as `previous_response_id`	Send earlier turns in `input`
402	`ertas_endpoint_inactive`	API access isn't activated	Verify a card or make a purchase
402	`credits_exhausted`	Not enough credits for this API call	Top up, or set a lower `max_tokens`
413	`request_too_large`	The request is larger than the model can accept	Send less
429	`rate_limit_error`	Over your plan's rate limit	Back off and retry
503	`ertas_endpoint_provisioning`	Your endpoint is still being set up	Retry after `Retry-After`
503	`deployment_starting` / `deployment_waking` / `deployment_unavailable`	The model is starting, restarting or at capacity	Retry after `Retry-After`
503	`ertas_billing_unavailable`	Your balance couldn't be checked	Retry after `Retry-After`
502	`upstream_unreachable`	The model couldn't be reached	Retry
500	`internal_error`	A problem on our side	Contact support with the Ray ID

Retry 429, 502 and 503. Wait for the number of seconds in Retry-After when it's present, and back off exponentially otherwise.
Don't retry 400, 401, 402 or 413 unchanged. The response carries x-should-retry: false where retrying can't help.
OpenAI SDKs retry 429 and 5xx responses by default. Raise max_retries if you want them to ride out a model restart, which can take a few minutes during the beta.

When you contact support, include the Ray ID from the cf-ray response header.