Developer guide
Error codes
What to do for each status code, and the retry rules
When the upstream returns a 4xx or 5xx, the gateway passes that code through unchanged; in all other cases it follows the rules in the table below.
400, 401, 403, 404, and 413 mean you need to fix the request or your configuration; 409, 429, and 5xx mean the client should wait and send the same request again.
The error body format differs by specification, and on the Anthropic-compatible path error.type is determined by the status code.
Use error.message to tell 403 reasons apart, and check limit and usage figures on the console pages.
Status codes
| Code | Meaning | What to do |
|---|---|---|
| 400 | A request value is invalid. This happens when limit on the Anthropic-compatible model list is outside 1 to 1000, or when you try to resume a stored response as a stream with GET /responses/{responseId}?stream=true. | Correct the value so it is within range. Retrieve stored responses without stream. |
| 401 | The key is missing, expired, or revoked. | Check the key status on the API keys page, and verify the header name and the Bearer prefix. |
| 403 | You do not have access to the model, have exceeded your usage limit, do not have enough credits, or are not the owner of the voice. | Check the reason in error.message, and look up the figures on the pages listed in the Checking limits and usage section below. |
| 404 | The model does not exist or is not accessible with this key (including models that are no longer supported). Also returned when you call a path that does not exist or request a CleviDrive artifact past its 3-day retention period. | First check the list of callable models with GET /models. Compare the path against the tables on the Calling the API page. |
| 408 · 409 · 413 | Upstream timeout, congestion, or request too large. On audio and voice paths, the timeout is 5 minutes and the request limit is 28 MiB. | If a 409 includes Retry-After, wait that long and then send the same request again. For 413, split the request into smaller parts. |
| 429 | The upstream provider applied a rate limit. | If Retry-After is present, wait that long and then resend; otherwise, retry with exponential backoff. |
| 5xx | A temporary error in the gateway or the upstream (including 503). | Retry with exponential backoff. If it keeps happening, contact us. |
The gateway never returns 402. Both insufficient credits and exceeded usage limits are returned as 403.
Retries and support
The gateway does not generate its own 429 responses, and it does not retry or queue upstream responses on your behalf. Waiting and retrying are the client's responsibility.
When you contact us, report the issue through Help & Support and include the X-Request-Id. If you did not send an X-Request-Id, the server-generated value is in the request-id header of Anthropic-compatible responses.
Error body
The error body format differs by specification. Upstream errors are trimmed down to the message before being passed on; stack traces and internal fields are not forwarded.
The error body on the OpenAI-compatible path.
{
"error": {
"message": "API key is required.",
"type": "invalid_request_error"
}
}The error body on the Anthropic-compatible path. error.type is determined by the status code as shown in the table below.
{
"type": "error",
"error": {
"type": "authentication_error",
"message": "..."
},
"request_id": "rqid..."
}| Status code | error.type |
|---|---|
| 400 | invalid_request_error |
| 401 | authentication_error |
| 403 | permission_error |
| 404 | not_found_error |
| 413 | request_too_large |
| 429 | rate_limit_error |
| 529 | overloaded_error |
| All other codes | api_error |
Checking limits and usage
Limit figures differ for each workspace. After checking the reason for a 403 in error.message, look up the figures on the following pages.
| What to check | Console page |
|---|---|
| The limits applied to your workspace | Allocated usage limits on the Overview page |
| What your plan allows and your remaining balance | Plan & Credits |
| Actual usage (calls by model and by key, estimated credit deduction) | Usage |
| Key status (expired or revoked) | API keys |