---
title: "Errors"
description: "Error bodies, every status the gateway returns, and what to do about each."
---

# Errors

Every endpoint except `/messages` returns errors in this shape. `error.code` is the HTTP status, not a provider code.

```json
{
  "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, a model that does not serve the endpoint, an unsupported variant, a bad `provider` object, `plugins` or `transforms` set, an `n` or a `best_of` that is not a whole number from 1 to 65536, an output limit (`max_tokens`, `max_completion_tokens`, `max_output_tokens`) that is not a whole number from 1 to 2147483647 (`1000`, `1000.0` and `1e3` are whole numbers), any of these fields sent more than once, or a request no host can take | Fix the request | No |
| 401 | No key, or a key that is unknown, disabled, expired or revoked. A key blocked by your account's [maximum key lifetime](../auth/api-keys.md#maximum-key-lifetime) gets the message `This key is blocked by your account's maximum key lifetime. Create a new key that expires within N days.` | Send a valid key, or create a key that expires within the limit | No |
| 402 | The balance cannot cover the most this request could cost, or the key reached its spend limit | Add credits at `/settings/credits`, lower `max_tokens` (on `/embeddings`, send less input), 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 | The details for the model could not be read | Retry later | No |
| 502 | The host returned an error, or a response cut off, unreadable or over its size cap: 32 MB, or on `/embeddings` a cap set by the request (below) | Retry; the message carries the request id | See below |
| 503 | The gateway cannot check keys, the balance or usage for a moment, or on `/embeddings` another large answer is being read | 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.
Before a request runs, the gateway holds the most it could cost: the prompt plus `max_tokens` of output, or 4,096 output tokens when the request sets no maximum. On `/embeddings` it holds the input alone. When the balance, less what requests in flight hold, cannot cover that, the answer is 402, even if the request would have cost less.
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](../features/usage-accounting.md) explains charges.

Before a request runs, the gateway holds its most possible cost: the prompt plus the longest answer allowed, your `max_tokens` or else the model's maximum.
When funds are short, one request holds an eighth of what is left, or the cost of a 4,096 token answer if that is more; the answer's limit is lowered to fit, and the `X-PG-Output-Cap` header gives the new limit.
A 402 means what is left cannot pay for the prompt, any thinking budget and a 4,096 token answer, or your smaller `max_tokens`; a key's spend limit works the same way.

On `/embeddings`, a model that is unknown or is not an embedding model returns 400 `Model <id> does not exist`, with no `metadata` and no `user_id`, as on OpenRouter. An embedding model sent to a chat endpoint gets that endpoint's unknown model 400. A host's 400, such as an input over 8,192 tokens, comes back as `HTTP 400: ` followed by the host's body. Once the host has answered 200, an embeddings answer that is cut off, unreadable, over its cap or not collected by the client is still charged at the input estimate, because the host was paid.
An embeddings answer's size cap follows the request: the number of inputs times the numbers in each vector (`dimensions`, or 3,072 when you name none), at most about 206 MB for 2,048 vectors of 3,072 numbers. A request whose answer could pass 32 MB is served one at a time: while one is being read, another such request gets 503 `the gateway is busy with other large answers; try again shortly` before any charge. See [Embeddings](embeddings.md#limits).
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](../features/rate-limits.md). 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](../routing/provider-routing.md#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

```sh
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
HTTP/1.1 401
{
  "error": {
    "message": "User not found.",
    "code": 401
  }
}
```
