Skip to main content

Errors

Is it Proxium or the vendor?​

You getOriginA vendor was called
401, 400, 413, 415, 422Proxium refused the requestNo
429 with retry-after: 60A ceiling of the key or the appNo
503 upstream_failedEach model of the plan failed. The message gives the reason of the last attemptYes
4xx upstream_refusedEach model of the plan refused the request. The status and the message are the first vendor'sYes
503 upstream_error, bad_upstream_response, video_failedThe vendor of a media callYes
503 keystore_unavailable, limits_unavailableProxium cannot read a storeNo

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:

codeMessageCeiling
tenant_cappedkey budget exceeded (<ceiling>), where <ceiling> is calls, cost, rpm or tpmA ceiling of the virtual key
source_cappedsource budget exceeded for '<app>' (<ceiling>), where <ceiling> is calls or costA 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 gatewayThe sentence that a person readsWhat to do
ContextExceededThe input is longer than this model accepts.Send fewer tokens, or choose a model with a larger input.
emptyThe answer was cut at max_tokens before any content.Raise max_tokens for this call.
QuotaExhaustedThe vendor's quota for the period is used up.Add a credit or raise the quota at the vendor.
RateLimited, status 429The vendor's rate limit refused the call.Send fewer calls at once, or wait for the vendor's limit to reset.
ModelUnsupported, status 404The vendor does not serve this model name.Choose another model for this tier in Routing.
status 401, 403The vendor refused the key.Replace the key of the vendor in Bring your own key.
NonRetryable, status 400The 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 5xxThe vendor failed (status 500).Try again, or choose another vendor for this tier in Routing.
upstream sendThe call stopped before the vendor sent an answer.Try again, or choose another vendor for this tier in Routing.
a pause after failuresProxium 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)"
}
}
Statuserror.type
400, 415, 422invalid_request_error
401authentication_error
402, 403permission_error
404not_found_error
413request_too_large
429rate_limit_error
529overloaded_error
Any other statusapi_error

Plain-text errors​

Some errors come before Proxium reads the body. Their body is plain text.

StatusCauseRoutes
400The body is not valid JSON, or a path id is not a UUIDEach POST route except chat/completions and messages, and memory/*
413The body is larger than the limitAll routes
415The content type is not JSONEach route except chat/completions and messages
422The JSON does not match the body schemamemory/*

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​

CodeStatusCauseFixRetry
missing_key401The request has no virtual keySend Authorization: Bearer <key>. On /v1/messages, x-api-key also worksNo
invalid_key401The key is not valid, revoked or expiredMake a new key on Endpoints or KeysNo
invalid_token401The token of proxium token is not valid or expiredRun proxium token for a new token. If the login expired, run proxium loginNo
forbidden_project403The token is not of a member of the project in x-proxium-projectName a project that you are a member ofNo
project_required400The token names several projects, and the request has no x-proxium-projectSend x-proxium-project with the project slugNo
no_project403The token names no projectRun proxium login, which makes a projectNo
keystore_unavailable503Proxium cannot read the key storeWait, then retryYes
limits_unavailable503Proxium cannot read the limits of the keyWait, then retryYes

Request​

CodeStatusRoutesCauseFixRetry
bad_json400chat/completionsThe body is not a valid chat requestFix the field that the message namesNo
unsupported_media_type415chat/completionsThe content type is not JSONSend Content-Type: application/jsonNo
missing_model400completions, embeddings, moderations, rerank, responses, images/generations, audio/speech, audio/transcriptions, audio/translationsNo model, or an empty oneSend a modelNo
bad_model400images/generations, video/generationsThe model id has a character other than a letter, a digit, ., _, - or :Send an id from GET /v1/modelsNo
missing_operation400video/operationsNo operationSend the operation of video/generationsNo
missing_uri400video/downloadNo uriSend the video_uri of the finished videoNo
forbidden_target400video/operations, video/downloadThe address is not a Google API hostSend the address that the video vendor gaveNo
invalid_memory_mode400Inferencex-proxium-memory is not write, recall or offFix the headerNo
invalid_memory_subject400chat/completions, messages, responsesx-proxium-memory-subject is too long, has a control character, or is not UTF-8Fix the headerNo

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​

CodeStatusRoutesCauseFixRetry
no_route400Inference, mediaNo model of the route is open to this key. The message tells whySee the table belowNo
context_too_long400InferenceThe 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 windowSend a shorter prompt, or add a model with a larger window to the tierNo
upstream_failed503Inference, mediaEach attempt of the plan failed, or the vendor could not be reachedRead the attempts on RequestsYes, with a wait
upstream_refusedThe first vendor's 4xxInferenceEach model of the plan refused the request. The message is the first vendor'sChange the request as the message saysNo
upstream_error503MediaThe vendor answered with an error. The message holds its status and bodyFix the request for that vendor, or the vendor keyNo
bad_upstream_response503images/generations, audio/speech, video/generationsProxium cannot read the answer of the vendorRetry. Then try a different modelYes
video_failed503video/operationsThe vendor reports that the video failedStart a new videoNo
bad_shape500MediaThe vendor configuration names an unknown answer shapeUse a different vendor for this typeNo

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 messageCauseFix
no models available for routeNo vendor of the project serves this model or tier, and the catalog fill adds none, or your failover policy has the catalog fill offAdd 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 routeUse an allowed model, or a different key
no providers configuredNo vendor at allAdd a vendor on Providers
no image provider configured, no tts provider configured, no video provider configuredNo vendor of this typeSend 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 typeAdd 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 typeUse an id from GET /v1/models

If x-proxium-timeout-ms ends, the message of upstream_failed starts with client deadline exceeded.

Ceilings​

CodeStatusCauseFixRetry
tenant_capped429The key reached a ceiling: calls, cost, rpm or tpmWaitAfter retry-after
source_capped429The app reached its ceiling: calls or costWait, or raise the ceiling in Overview › Per-app burnAfter retry-after

Data protection​

CodeStatusCauseFixRetry
classifier_blocked403A rule of the app's classification document blocks the call, and its condition held on the answers. The message names the reason of the ruleChange the request, or the ruleNo
guardrail_blocked403A class of Data protection set to block matched the request. The message names the class and the place in the request, never the valueRemove the value in your app, or change the action of the classNo

Memory​

These codes come from the memory/* routes.

CodeStatusCauseFixRetry
bad_request400A field is missing or wrong, or the text is empty or too longFix the field that the message namesNo
too_many_inputs400A moderation has more than 256 inputs. Each input is one callSend at most 256 inputs in one requestNo
forbidden403The key sent pinned: true, or a person wrote the memory that the key tried to changeLeave out pinned. Ask a person to change the memoryNo
not_found404No such conversation or live memoryCheck the idNo
memory_off409Memory is off for the projectTurn memory on in SettingsNo
query_failed500A database query failedWait, then retryYes

Errors in a stream​

When the failure comesYour app gets
Before the first pieceA normal error status and body, as above. No stream opens
After the first piece, OpenAI formatThe stream stops. No data: [DONE] follows
After the first piece, Anthropic formatAn 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​

CodeStatusWhen a deployment sends it
subscription_required402The project may not send calls. proxium.tech is in open beta
budget_unavailable503The budget store is down and the deployment refuses calls. proxium.tech lets the call through