> ## 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` | *Requests from this IP address are not allowed for your organization...* | Your organization restricts requests to [allowed IPs](https://docs.requesty.ai/features/compliance-report.md#allowed-ips) and this request came from another address. | Send the request from an allowed address, or ask an admin to add it on the [Compliance](https://app.requesty.ai/compliance) page. |
| **403** | `router` | *Provider blocked by policy* | The requested model is not in the [approved models](https://docs.requesty.ai/features/approved-models.md) or [access list](https://docs.requesty.ai/features/access-lists.md) 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](https://docs.requesty.ai/features/api-limits.md). |

***

## 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](https://docs.requesty.ai/api-reference/endpoint/chat-completions-create.md). 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. |
| **413** | `router` | *Request body exceeds the size limit. Send fewer or smaller images and files, or compact the conversation history. Limit = {limit} MB* | The request body is larger than the endpoint allows: 50 MB for chat completions, messages, responses, embeddings, decisions, image generation and speech; 32 MB for audio transcriptions; 20 MB for image edits. | Send fewer or smaller images and files, or drop older conversation turns, especially base64 images resent in long histories. |
| **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-6-sol`, `anthropic/claude-sonnet-5-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](https://docs.requesty.ai/features/reasoning.md) 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](https://docs.requesty.ai/features/bring-your-own-keys.md) 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](https://docs.requesty.ai/features/fallback-policies.md) 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](https://docs.requesty.ai/features/fallback-policies.md) 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](https://docs.requesty.ai/features/fallback-policies.md). |
| **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](https://docs.requesty.ai/features/fallback-policies.md) 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](https://docs.requesty.ai/features/fallback-policies.md). |

> [!NOTE]
>
> Requesty automatically retries provider errors when you use a [Routing Policy](https://docs.requesty.ai/features/fallback-policies.md) 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` | *Your organization reached its limit of concurrent requests* | Your organization exceeded its [in-flight request limit](https://docs.requesty.ai/features/in-flight-rate-limits.md), which is your balance multiplied by your organization tier's multiplier. | Retry once a request finishes, top up your balance to raise the limit, or contact [support@requesty.ai](mailto:support@requesty.ai). |
| **429** | `router` | *You reached your user-level limit of concurrent requests* | Your user, group, or service account exceeded its [in-flight request limit](https://docs.requesty.ai/features/in-flight-rate-limits.md). | Reduce parallelism, or ask an organization admin to raise the limit for your user. |

***

## 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](https://docs.requesty.ai/features/guardrails.md) in the Requesty dashboard. |
| **400** | `router` | *Request violated security policy* | The request content triggered a [guardrail](https://docs.requesty.ai/features/guardrails.md) 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`).

> [tab] Router error (your request)
>
> ```json HTTP 400 theme={"dark"}
> {
>   "error": {
>     "origin": "router",
>     "message": "Invalid model, expected: \"provider/model\""
>   }
> }
> ```

> [tab] Provider error (upstream)
>
> ```json HTTP 529 theme={"dark"}
> {
>   "error": {
>     "origin": "provider",
>     "message": "The provider is overloaded, please try again"
>   }
> }
> ```

***

## Best Practices

> [card] [Use Routing Policies](https://docs.requesty.ai/features/fallback-policies.md)
>
> Set up fallback chains so provider errors (429, 502, 503, 529) automatically retry on a different model — your application never sees the error.

> [card] [Set Spend Limits](https://docs.requesty.ai/features/api-limits.md)
>
> Configure per-project or per-key spend limits to avoid unexpected 402 errors from balance exhaustion.

> [card] [Monitor with Logs](https://docs.requesty.ai/features/logs.md)
>
> Use the Logs view to inspect individual request errors, filter by status code, and debug issues in real time.

> [card] [Check the Model Library](https://app.requesty.ai/model-library)
>
> Verify model names, providers, and capabilities before making requests to avoid 404 and 400 errors.

> [!TIP]
>
> **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.

> [!TIP]
>
> **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](https://docs.requesty.ai/features/fallback-policies.md) for automatic failover |
| 529 | Yes | Provider overloaded, retry with backoff |
| 500 | Maybe | Retry once, then contact support if persistent |

> [!TIP]
>
> **Use routing policies for automatic recovery.** Instead of implementing retry logic in your application, create a [routing policy](https://docs.requesty.ai/features/fallback-policies.md) with multiple models. Requesty automatically retries on provider errors (429, 502, 503, 529) using the next model in your fallback chain.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.