Errors

The OpenAI error shape

Each endpoint except /v1/messages sends an error in the OpenAI shape. type and code hold the same value.

{
  "error": {
    "message": "invalid or revoked key",
    "type": "invalid_key",
    "code": "invalid_key"
  }
}

Field	Meaning
error.message	The text for a person
error.type	The proxium code, for example no_route
error.code	The same value as error.type

The Anthropic error shape

/v1/messages sends each JSON error in the Anthropic shape. The plain-text errors below are the exception. error.type comes from the HTTP status, and error.message holds the text. The proxium code is not in the body.

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "tenant 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
Any other status	api_error

Plain-text errors

Some errors come before proxium reads the body. Their body is plain text, not JSON.

Status	Cause	Endpoints
400	The body is not valid JSON, or a path id is not a UUID	All POST endpoints except chat/completions and messages, and memory/*
413	The body is larger than 32 MiB	All endpoints
415	The content type is not JSON	All endpoints except chat/completions and messages
422	The JSON does not match the body schema	memory/*

Error codes

The Endpoints column leaves out the /v1 prefix. "Inference" means chat/completions, messages, embeddings, moderations, rerank and responses. "Media" means images/generations, audio/speech and video/*.

Authentication

These codes can come from every endpoint.

Code	Status	Meaning	What to do
missing_key	401	The request has no Authorization: Bearer header	Send the virtual key as a bearer token. With the Anthropic SDK, use auth_token
invalid_key	401	The key is not valid, or it is revoked	Check the key. Make a new one on the Keys screen
keystore_unavailable	503	proxium cannot read the key store	Retry after a short wait
limits_unavailable	503	proxium cannot read the limits of the key	Retry after a short wait

Request

Code	Status	Endpoints	Meaning	What to do
bad_json	400	chat/completions	The body is not a valid chat request	Fix the body. The message names the field
unsupported_media_type	415	chat/completions	The content type is not JSON	Send Content-Type: application/json
missing_model	400	embeddings, moderations, rerank, responses, images/generations, audio/speech	The body has no model, or it is empty	Send a model
bad_model	400	images/generations, video/generations	The model id has a character that is not a letter, a digit, ., _, - or :	Send a model id from GET /v1/models
missing_operation	400	video/operations	The body has no operation	Send the operation from the answer of video/generations
missing_uri	400	video/download	The body has no uri	Send the uri of the finished video
forbidden_target	400	video/operations, video/download	The address is not a Google API host	Send the address that the video provider gave
invalid_memory_mode	400	Inference	x-proxium-memory is not write, recall or off	Fix the header value
invalid_memory_subject	400	chat/completions, messages, responses	x-proxium-memory-subject is longer than 256 characters, holds a control character, or is not UTF-8	Fix the header value

In /v1/messages, a missing model or max_tokens gets 400 invalid_request_error. The message is model: Field required or max_tokens: Field required.

Routing and providers

Code	Status	Endpoints	Meaning	What to do
no_route	400	Inference, media	No model of the route is available to this key. The message tells why	Read the message. Refer to the table below
upstream_failed	502	Inference, media	Each attempt of the failover chain failed, or proxium could not reach the provider. The message gives the reason of the last attempt	Read the reason on the Requests screen. Retry, or add a model to the chain
upstream_error	502	Media	The provider answered with an error status. The message holds the status and the body of the provider	Fix the request for that provider, or check your vendor key
bad_upstream_response	502	images/generations, audio/speech, video/generations	proxium cannot read the answer of the provider	Retry. If it fails again, use a different model
video_failed	502	video/operations	The provider reports that the video failed	Start a new video
bad_shape	500	Media	The provider configuration names an answer shape that proxium does not know	Use a different provider for this request type

The message of no_route tells the cause:

Message	Cause	What to do
no models available for route	The project has no provider that serves this model or tier	Add a vendor on the Providers screen
model not permitted for this key: …	The model allow-list of the key refuses each model of the route	Use a model that the key allows, or a different key
no providers configured	proxium has no provider at all	Add a vendor on the Providers screen
no image provider configured, no tts provider configured, no video provider configured	The project has no default provider for this request type	Send a provider/model id of a provider that serves this request type
unknown image provider '…', unknown tts provider '…'	The provider in model does not serve this request type	Use a provider id from GET /v1/models

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

Budgets and ceilings

Code	Status	Meaning	What to do
tenant_capped	429	The virtual key reached one of its ceilings. The message names it: calls, cost, rpm or tpm	Wait for the time in retry-after, 60 seconds
source_capped	429	The application in x-proxium-source reached its own ceiling	Wait for the time in retry-after, 60 seconds. Or raise the ceiling of the application under Per-app burn on Overview

The message tells which limit refused the call. On /v1/messages, the message is the only way to tell the two 429 codes apart.

Code	Message
tenant_capped	tenant budget exceeded (<ceiling>), where <ceiling> is calls, cost, rpm or tpm
source_capped	source budget exceeded for '<application>' (<ceiling>)

For the ceilings, refer to Budgets and limits.

Memory

These codes come from the memory/* endpoints.

Code	Status	Meaning	What to do
bad_request	400	The body is missing, a field has a bad value, the text is empty or too long, or the subject is not valid	Fix the body. The message names the field
forbidden	403	The key sent pinned: true, or a person wrote the memory that the key tried to change or remove	Leave out pinned. Ask a person to change the memory in the console
not_found	404	The project has no such conversation or live memory	Check the id
memory_off	409	Memory is off for the project	Turn memory on under Settings
query_failed	500	A database query failed	Retry after a short wait