# Errors & limits

> Make failures understandable and give your application a useful recovery path.

## Common responses

| Status | Meaning                                                                                        | Next step                                                                                                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | The request does not match the supported API.                                                  | Check the model, message content, and parameters.                                                                                                                                |
| 401    | Authentication failed.                                                                         | Check the key and bearer header.                                                                                                                                                 |
| 402    | Shared credits, monthly cap, or request credit limit is insufficient.                          | Check the exact error code and your spending limits.                                                                                                                             |
| 409    | A selected offer or price changed, or the `Idempotency-Key` conflicts with an earlier request. | Review the offer, then explicitly choose its current price, another offer, or Auto. For request IDs, see [retries](https://router.optimai.network/docs/retries-and-timeouts.md#reuse-the-request-id-for-a-retry). |
| 429    | An account request or concurrency limit was reached.                                           | Reduce concurrent work and respect retry guidance.                                                                                                                               |
| 503    | Capacity or a required dependency is unavailable.                                              | Inspect the error code and `Retry-After`.                                                                                                                                        |

## No available provider

`no_priced_provider_available` means no eligible priced provider can accept your selected model now. `request_capacity` means Router’s global request capacity is full. `no_provider_for_length` means no online provider serves a request this long right now; shorten it, or wait for `Retry-After` (60 seconds) rather than retrying immediately. These return 503.

For manual selection, `provider_price_changed` and `provider_offer_unavailable` return 409; `selected_provider_unavailable` returns 503. Router does not silently choose another offer or Auto. Review the [provider selection recovery steps](https://router.optimai.network/docs/choosing-a-provider.md#recover-deliberately).

> **Recovery belongs in your application**
> Use bounded retries and respect `Retry-After`. Router does not keep requests in a waiting queue, silently substitute models, or automatically fail over to another attempt.

## Input and output limits

The API enforces model-specific limits alongside platform ceilings. Discover the current edition configuration before sending long prompts.

| Limit                       | Current platform ceiling                        |
| --------------------------- | ----------------------------------------------- |
| Messages                    | 16 per request                                  |
| Combined context            | 32,768 tokens                                   |
| Generated output            | 2,048 tokens (512 when `max_tokens` is omitted) |
| Combined message text       | 196,608 UTF-8 bytes                             |
| In-flight work per provider | 1 request                                       |

A configured model edition can be lower, and never exceeds its upstream model’s native context. Input longer than the context window is rejected with `context_length_exceeded`; output that fills the remaining context ends with `finish_reason: "length"`. Unsupported generation parameters are rejected explicitly.

## Account request limits

Default account limits are 60 model or chat requests per minute and 2 simultaneous inference requests. They are shared by every key and signed-in token for the account. A new key does not create a new allowance.

Router also starts with a 100-credit cap per UTC calendar month and a 5-credit maximum charge per request. The shared spendable balance, monthly allowance, and per-request maximum are checked separately. Reservations count against the cap until they settle or release.

An opted-in API key can have its own lower monthly limit. `api_key_budget_exhausted` means that key's limit is reached; another key cannot bypass the shared account cap. Key and account limits reset at the start of each UTC month.

## Usage is a measurement

Paid serving uses automatically eligible enrolled devices and their reported token counts. Those counts are not independently verified; missing or invalid usage does not become zero. The owner-scoped credit receipt, rather than the operational usage chart, records the final charge or unresolved settlement state.

For exact error envelopes and streaming failures, use the [error response reference](https://router.optimai.network/docs/api/errors.md).