Errors
Is it Proxium or the vendor?
| You get | Origin | A vendor was called |
|---|---|---|
401, 400, 413, 415, 422 | Proxium refused the request | No |
429 with retry-after: 60 | A ceiling of the key or the app | No |
503 upstream_failed | Each model of the plan failed. The message gives the reason of the last attempt | Yes |
4xx upstream_refused | Each model of the plan refused the request. The status and the message are the first vendor's | Yes |
503 upstream_error, bad_upstream_response, video_failed | The vendor of a media call | Yes |
503 keystore_unavailable, limits_unavailable | Proxium cannot read a store | No |
A 503 has two origins: a vendor failure, or a store of Proxium that is down. The code tells which.
Every model of the plan can refuse the request, for example a video file that no model can read. Then your app gets the status and the message of the first vendor, with the code upstream_refused. When any model fails in another way, your app gets 503 upstream_failed. To see the answer of each vendor, open the call in Requests. See Debug a failed call.
Which 429 is this?
Proxium sends a 429 only for its own ceilings. The code and the message tell which one:
code | Message | Ceiling |
|---|---|---|
tenant_capped | key budget exceeded (<ceiling>), where <ceiling> is calls, cost, rpm or tpm | A ceiling of the virtual key |
source_capped | source budget exceeded for '<app>' (<ceiling>), where <ceiling> is calls or cost | A ceiling of the app in x-proxium-source |
project_capped, app_capped, end_user_capped | <period> cap of this <scope> is used up (<dimension>) | A cap of the project, of the app or of the end user (see Set a cap) |
Both carry retry-after: 60. On /v1/messages, the body has no code, so read the message.
A 429 of a vendor does not reach your app while another vendor of the plan can answer. Proxium skips the 429 vendor for the rest of the request. Later calls of your project skip it for 60 seconds by default, or for its Retry-After when that is longer. Bring back ends it sooner. A key of Proxium is shared by every project. A person of your project ends its park for your project. An operator ends its park for every project. When every vendor of the plan is paused, your app gets 429 rate_limited with retry-after.
Why an attempt failed, in words
The gateway keeps the exact reason of each attempt, such as ContextExceeded status=400 or QuotaExhausted status=429. Proxium turns each reason into one sentence for a person. The Performance page shows the sentence in Failures by reason. The MCP tool proxium_list_failures returns the same sentence in the field cause of each group.
| The reason of the gateway | The sentence that a person reads | What to do |
|---|---|---|
ContextExceeded | The input is longer than this model accepts. | Send fewer tokens, or choose a model with a larger input. |
empty | The answer was cut at max_tokens before any content. | Raise max_tokens for this call. |
QuotaExhausted | The vendor's quota for the period is used up. | Add a credit or raise the quota at the vendor. |
RateLimited, status 429 | The vendor's rate limit refused the call. | Send fewer calls at once, or wait for the vendor's limit to reset. |
ModelUnsupported, status 404 | The vendor does not serve this model name. | Choose another model for this tier in Routing. |
status 401, 403 | The vendor refused the key. | Replace the key of the vendor in Bring your own key. |
NonRetryable, status 400 | The vendor refused the request (status 400): the model name or the request is not valid for it. | Check the model name in Routing, and the fields of the request. |
status 5xx | The vendor failed (status 500). | Try again, or choose another vendor for this tier in Routing. |
upstream send | The call stopped before the vendor sent an answer. | Try again, or choose another vendor for this tier in Routing. |
| a pause after failures | Proxium paused this model after recent failures. | Bring back ends the pause sooner. |
The OpenAI error shape
Each route except /v1/messages sends an error in this shape. type and code hold the same value.
{
"error": {
"message": "invalid or revoked key",
"type": "invalid_key",
"code": "invalid_key"
}
}
The Anthropic error shape
/v1/messages sends each JSON error in the Anthropic shape. error.type comes from the status. The Proxium code is not in the body.
{
"type": "error",
"error": {
"type": "rate_limit_error",
"message": "key budget exceeded (calls)"
}
}
| Status | error.type |
|---|---|
| 400, 415, 422 | invalid_request_error |
| 401 | authentication_error |
| 402, 403 | permission_error |
| 404 | not_found_error |
| 413 | request_too_large |
| 429 | rate_limit_error |
| 529 | overloaded_error |
| Any other status | api_error |
Plain-text errors
Some errors come before Proxium reads the body. Their body is plain text.
| Status | Cause | Routes |
|---|---|---|
| 400 | The body is not valid JSON, or a path id is not a UUID | Each POST route except chat/completions and messages, and memory/* |
| 413 | The body is larger than the limit | All routes |
| 415 | The content type is not JSON | Each route except chat/completions and messages |
| 422 | The JSON does not match the body schema | memory/* |
Error codes
The Routes column leaves out /v1. "Inference" is chat/completions, completions, messages, embeddings, moderations, rerank and responses. "Media" is images/generations, audio/speech, audio/transcriptions, audio/translations and video/*.
Authentication
| Code | Status | Cause | Fix | Retry |
|---|---|---|---|---|
missing_key | 401 | The request has no virtual key | Send Authorization: Bearer <key>. On /v1/messages, x-api-key also works | No |
invalid_key | 401 | The key is not valid, revoked or expired | Make a new key on Endpoints or Keys | No |
invalid_token | 401 | The token of proxium token is not valid or expired | Run proxium token for a new token. If the login expired, run proxium login | No |
forbidden_project | 403 | The token is not of a member of the project in x-proxium-project | Name a project that you are a member of | No |
project_required | 400 | The token names several projects, and the request has no x-proxium-project | Send x-proxium-project with the project slug | No |
no_project | 403 | The token names no project | Run proxium login, which makes a project | No |
keystore_unavailable | 503 | Proxium cannot read the key store | Wait, then retry | Yes |
limits_unavailable | 503 | Proxium cannot read the limits of the key | Wait, then retry | Yes |
Request
| Code | Status | Routes | Cause | Fix | Retry |
|---|---|---|---|---|---|
bad_json | 400 | chat/completions | The body is not a valid chat request | Fix the field that the message names | No |
unsupported_media_type | 415 | chat/completions | The content type is not JSON | Send Content-Type: application/json | No |
missing_model | 400 | completions, embeddings, moderations, rerank, responses, images/generations, audio/speech, audio/transcriptions, audio/translations | No model, or an empty one | Send a model | No |
bad_model | 400 | images/generations, video/generations | The model id has a character other than a letter, a digit, ., _, - or : | Send an id from GET /v1/models | No |
missing_operation | 400 | video/operations | No operation | Send the operation of video/generations | No |
missing_uri | 400 | video/download | No uri | Send the video_uri of the finished video | No |
forbidden_target | 400 | video/operations, video/download | The address is not a Google API host | Send the address that the video vendor gave | No |
invalid_memory_mode | 400 | Inference | x-proxium-memory is not write, recall or off | Fix the header | No |
invalid_memory_subject | 400 | chat/completions, messages, responses | x-proxium-memory-subject is too long, has a control character, or is not UTF-8 | Fix the header | No |
On /v1/messages, a missing max_tokens gets 400 invalid_request_error, with the message max_tokens: Field required. A model that is not a string gets the message model: Input should be a valid string. A missing model is not an error: the call uses auto, as on /v1/chat/completions.
Routing and vendors
| Code | Status | Routes | Cause | Fix | Retry |
|---|---|---|---|---|---|
no_route | 400 | Inference, media | No model of the route is open to this key. The message tells why | See the table below | No |
context_too_long | 400 | Inference | The prompt is longer than the context window of every model of the route whose window is known. The message gives the estimate and the largest window | Send a shorter prompt, or add a model with a larger window to the tier | No |
upstream_failed | 503 | Inference, media | Each attempt of the plan failed, or the vendor could not be reached | Read the attempts on Requests | Yes, with a wait |
upstream_refused | The first vendor's 4xx | Inference | Each model of the plan refused the request. The message is the first vendor's | Change the request as the message says | No |
upstream_error | 503 | Media | The vendor answered with an error. The message holds its status and body | Fix the request for that vendor, or the vendor key | No |
bad_upstream_response | 503 | images/generations, audio/speech, video/generations | Proxium cannot read the answer of the vendor | Retry. Then try a different model | Yes |
video_failed | 503 | video/operations | The vendor reports that the video failed | Start a new video | No |
bad_shape | 500 | Media | The vendor configuration names an unknown answer shape | Use a different vendor for this type | No |
On chat, Messages and the other JSON routes, Proxium answers no_route before it checks the ceilings, so the call uses no call slot. A model or vendor that your project retired never causes no_route: when every model of the plan is retired, Proxium calls them.
no_route message | Cause | Fix |
|---|---|---|
no models available for route | No vendor of the project serves this model or tier, and the catalog fill adds none, or your failover policy has the catalog fill off | Add a vendor on Providers, add a model to the tier, or turn the catalog fill on |
model not permitted for this key: … | The allow-list of the key refuses each model of the route | Use an allowed model, or a different key |
no providers configured | No vendor at all | Add a vendor on Providers |
no image provider configured, no tts provider configured, no video provider configured | No vendor of this type | Send a model id of a vendor of this type |
the tier '…' has no image models (or tts, stt, video) | A media call names a tier that has no models of this type | Add models of this type to the tier on Routing, or send a model id as provider/model |
unknown image provider '…', unknown tts provider '…' | The vendor in model does not serve this type | Use an id from GET /v1/models |
If x-proxium-timeout-ms ends, the message of upstream_failed starts with client deadline exceeded.
Ceilings
| Code | Status | Cause | Fix | Retry |
|---|---|---|---|---|
tenant_capped | 429 | The key reached a ceiling: calls, cost, rpm or tpm | Wait | After retry-after |
source_capped | 429 | The app reached its ceiling: calls or cost | Wait, or raise the ceiling in Overview › Per-app burn | After retry-after |
Data protection
| Code | Status | Cause | Fix | Retry |
|---|---|---|---|---|
classifier_blocked | 403 | A rule of the app's classification document blocks the call, and its condition held on the answers. The message names the reason of the rule | Change the request, or the rule | No |
guardrail_blocked | 403 | A class of Data protection set to block matched the request. The message names the class and the place in the request, never the value | Remove the value in your app, or change the action of the class | No |
Memory
These codes come from the memory/* routes.
| Code | Status | Cause | Fix | Retry |
|---|---|---|---|---|
bad_request | 400 | A field is missing or wrong, or the text is empty or too long | Fix the field that the message names | No |
too_many_inputs | 400 | A moderation has more than 256 inputs. Each input is one call | Send at most 256 inputs in one request | No |
forbidden | 403 | The key sent pinned: true, or a person wrote the memory that the key tried to change | Leave out pinned. Ask a person to change the memory | No |
not_found | 404 | No such conversation or live memory | Check the id | No |
memory_off | 409 | Memory is off for the project | Turn memory on in Settings | No |
query_failed | 500 | A database query failed | Wait, then retry | Yes |
Errors in a stream
| When the failure comes | Your app gets |
|---|---|
| Before the first piece | A normal error status and body, as above. No stream opens |
| After the first piece, OpenAI format | The stream stops. No data: [DONE] follows |
| After the first piece, Anthropic format | An error event, then the stream ends |
Proxium cannot move a stream to another model after the first piece. It does not cache a stream that stopped.
Codes that proxium.tech does not send today
| Code | Status | When a deployment sends it |
|---|---|---|
subscription_required | 402 | The project may not send calls. proxium.tech is in open beta |
budget_unavailable | 503 | The budget store is down and the deployment refuses calls. proxium.tech lets the call through |