Errors Code

Siraya AI 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": "Invalid API Key",
        "type": "invalid_request_error",
        "param": null,
        "code": 401
    }
}

Fields

Field	Type	Description
message	string	A human-readable description of the error.
type	string	The category of error (e.g., invalid_request_error, insufficient_quota).
param	string	The parameter that caused the error, if applicable.
code	number	The HTTP status code or a specific error code.

Common Error Codes

Code	Status	Description
400	Bad Request	The request was unacceptable, often due to missing parameters or invalid JSON.
401	Unauthorized	No valid API key was provided.
402	Payment Required	Your account balance is insufficient to complete the request.
403	Forbidden	The request was blocked (e.g., due to moderation policy).
408	Request Timeout	The connection to the model provider timed out.
429	Too Many Requests	You have reached your rate limit.
502	Bad Gateway	The model provider's server is down or unreachable.
503	Service Unavailable	No available model provider for the requested model.

Handling Errors

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

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

if (!request.ok) {
    const errorData = await request.json();
    console.error(`Error ${errorData.error.code}: ${errorData.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.