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
`403`	`key_expired`	The key is past its expiry date; see below
`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 (285 seconds 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. When a non-streaming request hits the gateway’s limit, the 504 also carries the response header x-should-retry: false. The official Anthropic and OpenAI SDKs (and Claude Code) read that header before their own retry rule, so they surface the error once instead of re-sending the same request into the same limit. Before retrying yourself, 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"
  }
}

Key not resolved yet (a newly created key): A key created moments ago can take a few seconds to propagate at the edge. If a request arrives in that window, the gateway refuses it rather than serve it without knowing which key it belongs to. Retry after a few seconds; the credential helper and tools such as Factory, Claude Code, and Claude Desktop retry on their own.

{
  "error": {
    "type": "authentication_error",
    "code": "key_identity_unresolved",
    "message": "The gateway could not resolve this API key yet. A newly created key can take a few seconds to propagate; retry."
  }
}

Key expired: Every key expires 12 months after it was created, and a key from SSO sign-in lasts 30 days. After that date the gateway refuses it. The credential helper signs you in again on its own; for any other key, create a replacement in the Consus portal and switch to it. Retrying the same key won’t help.

{
  "error": {
    "type": "key_expired",
    "message": "This key expired on 2027-10-20. Sign in again, or create a new key in the Consus portal."
  }
}

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: 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 this is a false positive, rename the parameter or contact Consus support."
  }
}

Request timed out (non-streaming limit):

HTTP 504 Gateway Timeout
x-should-retry: false

{
  "error": {
    "message": "The request did not complete within the 285s limit for non-streaming responses. Resend it with \"stream\": true, which allows a much longer response, or reduce max_tokens / effort.",
    "type": "timeout",
    "code": "buffered_timeout"
  }
}

Other 504 timeouts (for example a connection that never opened) keep the generic message and no x-should-retry header:

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

Unsupported input modality (an image or file sent to a model that cannot accept it):

{
  "error": {
    "message": "Model 'gpt-oss-120b' does not accept image input (accepted: text). Remove the image_url content part or choose a model whose input_modalities on GET /v1/models include \"image\".",
    "type": "invalid_request_error",
    "code": "unsupported_input_modality"
  }
}

When code is "unsupported_input_modality", the request was rejected before it reached any provider and can never succeed as sent — do not retry it. The message names the model, the part that was rejected (image_url or file), and the modality it needs. GET /v1/models → input_modalities is the authoritative list of what each model accepts; check it before attaching images or PDFs.

Rejected by the model provider’s content policy:

{
  "error": {
    "message": "The model provider's content policy rejected this request.",
    "type": "invalid_request_error",
    "code": "content_policy_violation"
  }
}

content_policy_violation means the model provider’s safety system rejected the request before generating anything (Azure content filter, Bedrock usage policy, or a Gemini prompt block). It’s a 400 and is not retried; rephrase the request or use a different model.

Responses stopped by provider safety

If a provider’s safety system stops a response mid-generation, the request still returns 200, with finish_reason: "content_filter" on /v1/chat/completions (stop_reason: "refusal" on /v1/messages).

Changed October 2026 (/v1/chat/completions): Claude refusals now return finish_reason: "content_filter" (was "stop"), and Bedrock stop-sequence matches return "stop" (was "length").

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

Responses stopped by provider safety

Errors on streaming requests

​Error Response Format

​Error Types

​Retries

​Common Errors

​Responses stopped by provider safety

​Errors on streaming requests

Error Response Format

Error Types

Retries

Common Errors

Responses stopped by provider safety

Errors on streaming requests