This page summarizes the status codes returned by the gateway and what they mean, along with the action to take for each code. If the upstream returns a 4xx or 5xx, the code is passed through unchanged. Otherwise, follow the table below. It also describes the error body formats for the two compatible 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 of 1–1000, or an attempt was made to resume a stored response with GET /responses/{responseId}?stream=true
Correct the value so it falls within the allowed range. Retrieve stored responses without stream.
401
The key is missing, expired, or revoked
Check the key status on the API key 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 values 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 multiple requests.
429
The upstream provider has applied a rate limit
If Retry-After is returned, follow it as is; otherwise, retry with exponential backoff.
5xx
A temporary error from the gateway or upstream (including 503)
Retry with exponential backoff. If the issue persists, report it through Help and Contact Us with X-Request-Id.
Retries
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
Resend the same request.
429
That amount of time if Retry-After is present; exponential backoff if not
Resend the same request.
5xx
Exponential backoff
Contact us if it persists.
413
No wait
Split the request.
Error body
The format of the error body varies by specification. Upstream errors are cleaned up and passed on with only the message; stacks and internal fields are not included.
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.
