API Reference

Error Handling

The OpenAI Responses API uses a consistent error format across all providers. This ensures that your integration remains robust even when switching between different underlying models. Errors returned before routing (API key, credits, rate limit, malformed JSON) have a different shape; see Errors Code.

Error Object

Errors returned after routing have the following shape. code is a string: a routing code from the table below, or the same value as type.

{
  "error": {
    "message": "Description of the error",
    "type": "error_type",
    "code": "error_code"
  }
}

Common Response API Errors

HTTP Status	Type	Code	Description
400	invalid_request_error	invalid_request_error	Invalid request parameters or body.
400	invalid_request_error	invalid_configuration	Invalid router configuration.
403	permission_denied	pool_access_denied	Access denied to the requested key pool.
404	invalid_request_error	model_not_found	No vendors found for the requested model.
503	service_unavailable	no_vendors_available	No vendors available for the requested model.
503	service_unavailable	all_vendors_cooling_down	All vendors are in cooldown after failures.
503	service_unavailable	max_failovers_exceeded	Maximum failover attempts exceeded across vendors.
503	service_unavailable	max_fallbacks_exceeded	Maximum model fallback attempts exceeded.

Upstream Vendor Errors

When the upstream vendor returns an error, it is mapped and returned in the same format. For 5xx statuses type follows the status and code carries the same value:

HTTP Status	Type	Description
400	invalid_request_error	Bad request or unsupported parameters.
400	context_length_exceeded	Input exceeds model context window.
400	content_policy_violation	Content violates vendor safety policy.
401	authentication_error	Invalid or missing API credentials at vendor.
403	permission_denied_error	Insufficient permissions at vendor.
404	not_found_error	Vendor model or resource not found.
408	timeout_error	Request to vendor timed out.
429	rate_limit_error	Vendor rate limit exceeded.
500	internal_error	Vendor internal server error.
502	api_error	Connection error to vendor API.
503	service_unavailable	Vendor temporarily unavailable.
504	api_error	Vendor did not respond within the request time budget.

Handling Errors in Code

import requests

response = requests.post(
    "https://llm.siraya.ai/v1/responses",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer <API_KEY>",
    },
    json={"model": "gpt-5.4-mini", "input": "Hello"}
)

if response.status_code != 200:
    error = response.json().get("error", {})
    print(f"Error: [{error.get('code')}] {error.get('message')}")

Example Response

{
  "error": {
    "message": "no vendors found for model: unknown-model",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}