Errors
Error bodies, every status the gateway returns, and what to do about each.
Every endpoint except /messages returns errors in this shape. error.code is the HTTP status, not a provider code.
{
"error": {
"message": "No endpoints found matching your provider.only list",
"code": 404,
"metadata": { "routing_funnel": [], "failed_routing_step": "Filter by Only" }
},
"user_id": "10000000-0000-0000-0000-000000000001"
}metadata is present only when there is detail: provider_name on a host error, routing_funnel and failed_routing_step when routing filters leave no host.
user_id (your account id) is sent on 400 answers once the key is known.
/messages uses Anthropic's shape: {"type": "error", "error": {"type": "authentication_error", "message": "...", "error_type": "authentication"}, "request_id": null}.
Statuses
| Status | Cause | What to do | Charged |
|---|---|---|---|
| 400 | Invalid JSON, no input, a missing or unknown model id, an unsupported variant, a bad provider object, plugins or transforms set, or a request no host can take |
Fix the request | No |
| 401 | No key, or a key that is unknown, disabled, expired or revoked | Send a valid key | No |
| 402 | The balance cannot cover this request, or the key reached its spend limit | Top up at /settings/credits, or raise the key's limit |
No |
| 404 | Unknown path, unknown generation id, unknown model on /endpoints, or no host left after routing filters |
Check the id, or relax the provider filters |
No |
| 408 | The host sent no answer in time | Retry | No |
| 413 | The request body is over 32 MiB | Send a smaller body | No |
| 429 | The last host tried rate limited the request | Wait for Retry-After when present, then retry |
No |
| 500 | A catalog entry could not be read | Retry later | No |
| 502 | The host returned an error, or a response cut off, unreadable or over 32 MB | Retry; the message carries the request id | See below |
| 503 | The gateway's key, billing or usage store is briefly unavailable | Retry after a short wait | No |
A host's own 4xx answer, such as a context length error, keeps its status. The message is Provider returned error, and metadata.raw carries the host's body.
A host's 401 or 403 means the host refused the gateway's credentials, so you get 502.
An error answered before the host produced output is not charged. A 502 for a response the host did finish, but that was over 32 MB or could not be translated, can be charged for the tokens the host reported. Usage accounting explains charges.
Before answering 408, 429 or 502 for a host that failed, timed out or rate limited, the gateway tries the next eligible host; see Rate limits. A 502 for a response that arrived but was unreadable comes back at once, without trying another host. With Allow fallbacks off in your account settings, the gateway tries one host per model.
Errors inside a stream
Once a stream has started, the status is already 200, so a failure arrives as a last event with the error body and metadata.provider_name, and the stream ends. Its error.code is 408 for a timeout and 502 otherwise.
Example
Request
curl https://api.plaingateway.com/api/v1/chat/completions \
-H "Authorization: Bearer sk-pg-v1-not-a-real-key" \
-H "Content-Type: application/json" \
-d '{"model": "openai/gpt-5.6-luna", "messages": [{"role": "user", "content": "Say hello in five words."}]}'Response
HTTP/1.1 401
{
"error": {
"message": "User not found.",
"code": 401
}
}