Skip to main content
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 StatusError TypeMeaning
400invalid_request_errorBad request: invalid model, missing fields, validation failure, or payload exceeds limits
401authentication_errorAuthentication failed
403permission_errorInvalid or missing API key, or access denied to the requested model
429rate_limit_errorRate limit or monthly quota exceeded
500server_errorInternal server error
502server_errorUpstream provider unavailable or returned a server error

​
Retries

Consus Gateway automatically retries transient upstream errors once before returning an error to you. The retry delay depends on the error type:
Upstream ErrorDelayReason
429 (rate limit)2 secondsUpstream provider needs time to reset
502 / 503 (server error)0.5 secondsTransient 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.

​
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."
  }
}
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.