Errors

Consus Gateway returns errors in the OpenAI error format so existing SDK error handling works without changes.

Error Response Format

{
  "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

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).

Common Errors

Invalid model:

{
  "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 for the full list and rationale.

{
  "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:

{
  "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:

{
  "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:

{
  "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) 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.

Product

Getting Started

API Reference

Integrations

Error Response Format

Error Types

Retries

Common Errors

Errors on streaming requests

​Error Response Format

​Error Types

​Retries

​Common Errors

​Errors on streaming requests

Error Response Format

Error Types

Retries

Common Errors

Errors on streaming requests