> ## Documentation Index
> Fetch the complete documentation index at: https://docs.requesty.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Error Codes
> Comprehensive reference for all Requesty router error codes, what they mean, and how to resolve them
When a request fails, Requesty returns a standard JSON error response with an HTTP status code and a human-readable message. Errors originate from either the **router** (Requesty's own validation and routing logic) or an upstream **provider** (OpenAI, Anthropic, Google, etc.).
```json Example error response (HTTP 404) theme={"dark"}
{
"error": {
"origin": "router",
"message": "Provider and/or model not supported"
}
}
```
The `origin` field tells you where the error came from — `"router"` means Requesty caught the problem before it reached a provider, while `"provider"` means an upstream LLM provider returned the error.
***
## Authentication & Authorization
Errors related to API key validation, account status, and access control.
| HTTP Code | Origin | Error Message | Description | What to Do |
| --------- | -------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **401** | `router` | *Unauthorized* | No `Authorization` header was provided, or it is empty. | Include `Authorization: Bearer sk-...` in your request headers. |
| **402** | `router` | *Insufficient balance, top up at: [https://app.requesty.ai/settings](https://app.requesty.ai/settings)* | Your organization's balance has been exhausted. | [Top up your balance](https://app.requesty.ai/settings) or contact your organization admin. |
| **403** | `router` | *Invalid authorization token* | The API key is invalid, expired, or revoked. | Generate a new API key at [app.requesty.ai/api-keys](https://app.requesty.ai/api-keys). |
| **403** | `router` | *Your account has been restricted...* | Your organization has been restricted due to a policy violation. | Contact [support@requesty.ai](mailto:support@requesty.ai) for more information. |
| **403** | `router` | *Provider blocked by policy* | The requested model is not in the [approved models](/features/approved-models) or [access list](/features/access-lists) for your API key. | Ask your admin to add the model to your access list, or use an approved model. |
| **412** | `router` | *Reached monthly spend limit for API key* | The monthly spending cap for your API key or project has been reached. | Wait for the next billing cycle, or ask your admin to increase the [spend limit](/features/api-limits). |
***
## Request Validation
Errors returned when the request payload is malformed or contains invalid parameters.
| HTTP Code | Origin | Error Message | Description | What to Do |
| --------- | -------- | ------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **400** | `router` | *Invalid request format* | The request body is malformed, missing required fields, or contains invalid JSON. | Check your request body against the [API reference](/api-reference/endpoint/chat-completions-create). Ensure valid JSON and required fields like `model` and `messages`. |
| **400** | `router` | *Request body is empty* | An empty request body was sent. | Provide a valid JSON request body. |
| **400** | `router` | *Invalid model, expected: "provider/model"* | The `model` field is not in the required `provider/model` format. | Use the format `provider/model` (e.g., `openai/gpt-4.1`, `anthropic/claude-sonnet-4-5`). See [available models](https://app.requesty.ai/model-library). |
| **400** | `router` | *Invalid model params* | Model parameters (region, reasoning effort, etc.) are invalid. | Check supported [model parameters](/features/reasoning) and region suffixes. |
***
## Model & Routing
Errors related to model resolution, routing policies, and plan compilation.
| HTTP Code | Origin | Error Message | Description | What to Do |
| --------- | -------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **404** | `router` | *Provider and/or model not supported* | The requested provider/model combination does not exist in Requesty's model library. | Check the [model library](https://app.requesty.ai/model-library) for available models. Verify the provider and model names are spelled correctly. |
| **400** | `router` | *Routing policy is unknown* | The referenced routing policy does not exist. | Verify the policy name in your `model` field (e.g., `policy/my-policy`). Create or check policies at [Routing Policies](https://app.requesty.ai/routing-policies). |
| **422** | `router` | *Routing policy uses forbidden models or BYOK is missing* | All models in the routing policy are either not in your access list, or require [BYOK](/features/bring-your-own-keys) credentials that haven't been configured. | Add the policy's models to your access list, or configure the required BYOK provider keys. |
| **500** | `router` | *Routing policy is corrupted* | The routing policy exists but failed to compile into a valid plan. | Re-create the routing policy, or contact support if the issue persists. |
| **500** | `router` | *Smart routing failed* | The smart routing classifier was unable to select a model. | Retry the request. If persistent, fall back to a specific model or policy. |
***
## Provider Errors
Errors originating from upstream providers (OpenAI, Anthropic, Google, Bedrock, etc.), translated and normalized by Requesty.
| HTTP Code | Origin | Error Message | Description | What to Do |
| --------- | ---------- | ---------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **429** | `provider` | *Too many requests* | The upstream provider returned a rate limit error. | Reduce request frequency, or create a [Routing Policy](/features/fallback-policies) to automatically failover to another provider. |
| **502** | `provider` | *Provider is down: Bad Gateway* | The upstream provider returned a 502 error. | Retry after a short delay. Consider setting up a [Fallback Policy](/features/fallback-policies) for automatic failover. |
| **502** | `router` | *There was a problem with the provider stream* | The provider sent an error within an SSE stream after streaming had started. | Retry the request. If consistent, try a different provider or model. |
| **503** | `router` | *The provider timed out, please try again* | The upstream provider did not respond within the timeout window. | Retry the request. For long-running requests, consider models with higher timeout allowances or use a [fallback policy](/features/fallback-policies). |
| **424** | `router` | *Invalid provider response format* | The provider returned a response that Requesty could not parse. | Retry the request. This is typically a transient provider issue. If persistent, contact support. |
| **424** | `router` | *Provider response missing usage* | The provider did not include token usage data in the response. | Retry the request. This is a transient provider issue. |
| **529** | `provider` | *The provider is overloaded, please try again* | The upstream provider is experiencing high load (common with Anthropic). | Wait and retry, or use a [fallback policy](/features/fallback-policies) to route to an alternative provider automatically. |
| **504** | `provider` | *Provider is down: Gateway timeout* | The upstream provider returned a 504 Gateway Timeout. | Retry after a short delay. Set up automatic failover with a [Routing Policy](/features/fallback-policies). |
Requesty automatically retries provider errors when you use a [Routing Policy](/features/fallback-policies) with multiple models. Provider rate limits (429), overload (529), timeouts (503), and bad gateway (502) errors all trigger automatic fallback to the next model in the chain.
***
## Rate Limiting
| HTTP Code | Origin | Error Message | Description | What to Do |
| --------- | ---------- | ----------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| **429** | `provider` | *Too many requests* | Upstream provider rate limit. | See [Provider Errors](#provider-errors) above. |
| **429** | `router` | *Too many simultaneous requests for user* | Your API key has exceeded the configured concurrent request limit. | Reduce parallelism, or ask your admin to increase the in-flight rate limit for your project. |
***
## Security & Guardrails
| HTTP Code | Origin | Error Message | Description | What to Do |
| --------- | -------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| **403** | `router` | *Provider blocked by policy* | The requested model is blocked by your organization's routing policy. | Use a model that is allowed by your policy, or ask your admin to update the policy. |
| **400** | `router` | *Request security policy not found* | A guardrail policy referenced in your configuration does not exist. | Verify [guardrail configuration](/features/guardrails) in the Requesty dashboard. |
| **400** | `router` | *Request violated security policy* | The request content triggered a [guardrail](/features/guardrails) violation with the `block` action. | Review and adjust your request content, or update guardrail settings if this is a false positive. |
***
## Connection & Client Errors
| HTTP Code | Origin | Error Message | Description | What to Do |
| --------- | -------- | -------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| **499** | `router` | *Client closed connection* | The client disconnected before the response completed. | Ensure your HTTP client has a sufficient timeout. For streaming requests, keep the connection open until the stream ends. |
| **499** | `router` | *Stream interrupted, please try again* | The streaming response was interrupted after some data was already sent. | Retry the request. Ensure a stable network connection. |
***
## Internal Errors
| HTTP Code | Origin | Error Message | Description | What to Do |
| --------- | -------- | ---------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **500** | `router` | *Internal server error* | An unexpected error occurred within the router. | Retry the request. If persistent, contact [support@requesty.ai](mailto:support@requesty.ai) with your request ID. |
| **500** | `router` | *Get API key configuration failed* | Requesty failed to load the configuration for your API key. | Retry the request. If persistent, this may indicate a temporary platform issue. |
| **500** | `router` | *Apply rate-limit failed* | The rate-limiting system encountered an internal error. | Retry the request. This is a transient infrastructure issue. |
***
## Context Length Errors
When your input exceeds a model's context window, Requesty translates the provider-specific error into a clear, actionable message.
| HTTP Code | Origin | Error Message | What to Do |
| --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **400** | `router` | *Your input is {actual} tokens, which exceeds the model's maximum context length of {max} tokens.* | Reduce your input by shortening messages, removing older conversation history, or summarizing prior context. |
| **400** | `router` | *Your input is {actual} tokens and max\_tokens is {max}, which together exceed the model's context limit of {limit} tokens.* | Lower `max_tokens` or shorten your input so that `input + max_tokens` stays within the model's context window. |
| **400** | `router` | *Your input exceeds the model's maximum context length.* | Shorten your messages. See the [model library](https://app.requesty.ai/model-library) for each model's context window. |
| **400** | `router` | *max\_tokens must be greater than thinking.budget\_tokens.* | Increase `max_tokens` or decrease `thinking.budget_tokens` in your request. |
***
## Error Response Format
All errors return JSON with the following structure:
```json theme={"dark"}
{
"error": {
"origin": "router",
"message": "Human-readable error description"
}
}
```
| Field | Type | Description |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `error.origin` | `string` | Where the error originated — `"router"` for Requesty errors, `"provider"` for upstream provider errors. |
| `error.message` | `string` | A human-readable description of the error. |
The HTTP status code is returned in the response status line (e.g., `HTTP/2 404`). The `origin` field helps you determine whether to fix your request (`router`) or retry / failover (`provider`).
```json HTTP 400 theme={"dark"}
{
"error": {
"origin": "router",
"message": "Invalid model, expected: \"provider/model\""
}
}
```
```json HTTP 529 theme={"dark"}
{
"error": {
"origin": "provider",
"message": "The provider is overloaded, please try again"
}
}
```
***
## Best Practices
Set up fallback chains so provider errors (429, 502, 503, 529) automatically retry on a different model — your application never sees the error.
Configure per-project or per-key spend limits to avoid unexpected 402 errors from balance exhaustion.
Use the Logs view to inspect individual request errors, filter by status code, and debug issues in real time.
Verify model names, providers, and capabilities before making requests to avoid 404 and 400 errors.
**Track errors in Advanced Analytics.** Group by `status_code` in [Advanced Analytics](https://app.requesty.ai/analytics/advanced?groupBy=status_code\&metric=cost\&aggMethod=sum\&timeRange=7d\&timeGroup=day) to see which errors are costing you the most and spot trends over time.
**Include request IDs in support tickets.** Every response includes an `x-request-id` header. When contacting support, include this ID so we can trace the exact request path through the router.
***
## Error Recovery and Retry Strategy
Implement exponential backoff with jitter for retryable errors. The following strategy works for all Requesty API calls:
```python theme={"dark"}
import time
import random
def call_with_retry(fn, max_retries=3, base_delay=1.0):
for attempt in range(max_retries + 1):
try:
return fn()
except Exception as e:
status = getattr(e, 'status_code', 0)
# Retry on 429, 502, 503, 529 only
if status not in (429, 502, 503, 529) or attempt == max_retries:
raise
delay = base_delay * (2 ** attempt) + random.uniform(0, 0.5)
retry_after = getattr(e, 'headers', {}).get('Retry-After')
if retry_after:
delay = max(delay, float(retry_after))
time.sleep(delay)
```
| Error | Retryable | Strategy |
| ------- | --------- | ------------------------------------------------------------------------------------------------- |
| 400 | No | Fix request payload |
| 401/403 | No | Fix credentials or permissions |
| 402 | No | Top up account balance |
| 429 | Yes | Respect `Retry-After` header, exponential backoff |
| 502/503 | Yes | Retry with backoff, or use a [routing policy](/features/fallback-policies) for automatic failover |
| 529 | Yes | Provider overloaded, retry with backoff |
| 500 | Maybe | Retry once, then contact support if persistent |
**Use routing policies for automatic recovery.** Instead of implementing retry logic in your application, create a [routing policy](/features/fallback-policies) with multiple models. Requesty automatically retries on provider errors (429, 502, 503, 529) using the next model in your fallback chain.