Errors Code

SIRAYA Model Router uses standard HTTP response codes to indicate the success or failure of an API request. In case of an error, the response body will contain a structured JSON object with details.

Error Response Format

Errors are returned as a JSON object with the following schema:

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

Fields

Field	Type	Description
message	string	Human-readable description of the error. Vendor-internal identifiers (request IDs, ARNs, GCP resource paths) are stripped.
type	string	Error category, useful for branching client-side logic.
code	string | number	Specific identifier. Either a string code (e.g. model_not_found) or the numeric HTTP status.

Common Error Codes

Code	Status	Description
400	Bad Request	Malformed JSON or invalid parameters. type is one of invalid_request_error, context_length_exceeded, content_policy_violation, rejected_request_error, unsupported_params_error.
401	Unauthorized	Missing or invalid API key, or upstream credentials were rejected. type is authentication_error.
403	Forbidden	The API key lacks permission for the requested model or routing pool. type is permission_denied_error (or permission_denied for routing errors).
404	Not Found	The requested model or resource does not exist. type is not_found_error, or invalid_request_error with code=model_not_found for routing errors.
408	Request Timeout	Upstream provider timed out, or the routing-service request budget elapsed. type is timeout_error.
422	Unprocessable Entity	The request was well-formed but semantically invalid. type is unprocessable_entity_error.
429	Too Many Requests	Rate limit reached. type is rate_limit_error. The retry_after field may be populated.
500	Internal Server Error	Unhandled error in routing-service or upstream provider. type is internal_server_error.
502	Bad Gateway	Upstream returned 502 or the connection to the provider failed. type is one of bad_gateway_error, api_connection_error, service_unavailable.
503	Service Unavailable	No vendor is available, all vendors are cooling down, or the failover/fallback budget was exhausted. type is service_unavailable.

Handling Errors

When using the OpenAI SDK or standard HTTP clients, always check the response status code.

const response = await fetch('https://llm.siraya.ai/v1/chat/completions', { /* ... */ });

if (!response.ok) {
  const data = await response.json();
  // `code` may be a string or a number, normalize it
  const code = String(data.error?.code ?? '');
  const type = data.error?.type ?? '';
  console.error(`[${response.status}] ${type} (${code}): ${data.error?.message}`);
}

Warm-up and Retries

Occasionally, a model may not generate content immediately during provider warm-up or scaling. We recommend implementing a retry mechanism with exponential backoff for 5xx and 408 errors.