This page summarises the status codes returned by the gateway, their meanings, and how to handle each code. If the upstream returns a 4xx or 5xx, the code is passed through unchanged; otherwise, the table below applies. It also describes the error body formats for the two compatibility specifications, the rules for Anthropic-compatible error.type, and the console screens for checking limits and usage.
Status code
Code
Meaning
Action
400
Invalid request value. The limit for the Anthropic-compatible model list is outside the range 1–1000, or an attempt was made to resume a stored response with GET /responses/{responseId}?stream=true
Correct the value so that it is within the range. Retrieve stored responses without stream.
401
Missing, expired, or revoked key
Check the key status on the API keys page and verify the header name and Bearer prefix.
403
No access to the model, usage limit exceeded, insufficient credits, or not the voice owner
error.message distinguishes the reason. Check the figures on the screens in the Limits and usage section below.
404
The model does not exist or cannot be accessed with this key (including models that are no longer supported), the path does not exist, or the CleviDrive output is more than 3 days past its retention period
First check the list of callable models with GET /models. Compare the path with the table on the Making API calls page.
408 · 409 · 413
Upstream timeout, congestion, or request size exceeded. For voice and voice paths, the time limit is 5 minutes and the request limit is 28 MiB
If 409 includes Retry-After, wait for that amount of time. For 413, split the request into smaller requests.
429
The upstream provider has applied a rate limit
If Retry-After is provided, follow it as given; otherwise, retry with exponential backoff.
5xx
Temporary gateway or upstream error (including 503)
Retry with exponential backoff. If the issue persists, report it via Help and Contact us with the X-Request-Id.
Retrying
The gateway does not generate its own 429 responses, nor does it silently retry or queue upstream responses. The client handles waiting and retries.
Code
Wait time
Then
409
That amount of time if Retry-After is present
Send the same request again.
429
That amount of time if Retry-After is present; exponential backoff if not
Send the same request again.
5xx
Exponential backoff
Contact support if it continues.
413
No wait
Split the request.
Error body
The format of the error body differs by specification. For upstream errors, we retain only the message, tidy it up and pass it on; stacks and internal fields are not forwarded.
Body for the OpenAI-compatible route.
{"error":{"message":"API key is required.","type":"invalid_request_error"}}
Body for the Anthropic-compatible route. error.type is determined by the status code.
