> ## Documentation Index
> Fetch the complete documentation index at: https://gateway.consus.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Errors
> Error types, formats, and retry behavior for Consus Gateway.
Consus Gateway returns errors in the OpenAI error format so existing SDK error handling works without changes.
## Error Response Format
```json theme={null}
{
"error": {
"message": "Description of what went wrong",
"type": "error_type"
}
}
```
Error messages returned to clients are sanitized. Raw provider details are never exposed. This prevents accidental leakage of prompt content through error responses.
## Error Types
| HTTP Status | Error Type | Meaning |
| ----------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `invalid_request_error` | Bad request: invalid model, missing fields, validation failure, or payload exceeds limits |
| `401` | `authentication_error` | Authentication failed |
| `403` | `permission_error` | Invalid or missing API key, or access denied to the requested model |
| `429` | `rate_limit_error` | Rate limit or monthly quota exceeded |
| `500` | `server_error` | Internal server error |
| `502` | `server_error` | Upstream provider unavailable or returned a server error |
| `504` | `timeout` | Request exceeded its maximum duration (5 minutes non-streaming, \~15 minutes streaming) — see [Request Timeout](/rate-limits#request-timeout) |
## Retries
Consus Gateway automatically retries transient upstream errors **once** before returning an error to you. The retry delay depends on the error type:
| Upstream Error | Delay | Reason |
| ---------------------------- | ----------- | ------------------------------------- |
| `429` (rate limit) | 2 seconds | Upstream provider needs time to reset |
| `502` / `503` (server error) | 0.5 seconds | Transient infrastructure blip |
For client-side retries, the OpenAI SDK has built-in retry logic that works out of the box. If you're using raw HTTP, retry on `429` and `502` with exponential backoff: start at 1 second, double each attempt, and cap at 5 retries.
`504` timeouts are **not** automatically retried — a request that exceeded its ceiling will usually exceed it again. Before retrying, either stream the request (`stream: true` raises the ceiling to \~15 minutes) or reduce the work in it (see [Request Timeout](/rate-limits#request-timeout)).
## Common Errors
**Invalid model:**
```json theme={null}
{
"error": {
"message": "The request was invalid. Check your parameters.",
"type": "invalid_request_error"
}
}
```
**Tool schema rejected for destination-bearing parameter:**
When a tool definition contains a parameter name that describes an outbound destination (for example `destination_url`, `webhook_url`, `callback_url`, `forward_to`, `send_to`, `post_to`, `upload_url`, `ingest_url`), the request is rejected at validation. The message identifies the tool and the offending parameter. See [Chat Completions: Rejected Tool Schemas](/endpoints/chat-completions#rejected-tool-schemas) for the full list and rationale.
```json theme={null}
{
"error": {
"type": "invalid_request_error",
"message": "tools -> 0 -> function: Value error, Tool 'save_results' has a parameter named 'destination_url' that suggests an outbound destination. Tools with destination-bearing parameters are rejected by gateway governance to prevent data exfiltration via tool calls. If you have a legitimate use case for this parameter name, contact Consus support for an exception."
}
}
```
**Request timed out:**
```json theme={null}
{
"error": {
"message": "Upstream provider did not respond in time. This usually means the request was too long or the model is under load.",
"type": "timeout"
}
}
```
**Rate limited (API Gateway):**
```
HTTP 429 Too Many Requests
```
**Upstream model rate limit:**
```json theme={null}
{
"error": {
"message": "Upstream model rate limit exceeded. This is a provider-side limit, not your API key limit. Please retry after a brief wait.",
"type": "rate_limit_error",
"code": "upstream_rate_limit"
}
}
```
When `code` is `"upstream_rate_limit"`, the 429 came from the upstream model provider, not from your API key's rate limit. API key rate limits are enforced at the API Gateway layer and return a `429` without a JSON body.
**Context window exceeded:**
```json theme={null}
{
"error": {
"message": "The request exceeds the model's context window (202,186 tokens > 200,000 maximum); reduce the input or max_tokens.",
"type": "invalid_request_error",
"code": "context_window_exceeded"
}
}
```
When `code` is `"context_window_exceeded"`, the request can never succeed as sent — **do not retry it**. Trim or compact the conversation (agent harnesses: see [Agent Harnesses & Context Windows](/agent-harnesses)) and resend. When the provider reports them, the message carries the attempted and maximum token counts.
## Errors on streaming requests
A request that fails **before the provider produces its first event** — validation rejections, context-window overflows, provider faults during setup — returns its real HTTP status and the JSON error body above, even when `stream: true` was requested. Branch on the status code exactly as you would for a non-streaming call; a `400` is terminal, a `502`/`503` is retryable.
Once streaming has begun (HTTP 200 committed and events flowing), a mid-stream failure is delivered **in-band**: an error frame on the SSE stream, followed by a clean close (`data: [DONE]` on `/v1/chat/completions`; an `error` event on `/v1/messages` and `/v1/responses`). Mid-stream errors after partial output are not automatically retryable — inspect the frame's `type` and `code` before resending.