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.

Error Object

All errors return a JSON response with the following shape:

{
  "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.
429	rate_limit_error	rate_limit_exceeded	You have sent too many requests in a short period.
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:

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_server_error	Vendor internal server error.
502	api_connection_error	Connection error to vendor API.
503	service_unavailable	Vendor temporarily unavailable.

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": "deepseek-v4-flash", "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"
  }
}