Error Codes

ORVEXA uses conventional HTTP status codes to indicate success or failure. All errors return a consistent JSON format with a message, type, and request ID.

Error Response Format

Every error response contains an error object with the following fields:

messageA human-readable description of what went wrong.

typeA machine-readable error category string (e.g., authentication_error).

paramThe parameter that caused the error, if applicable. null otherwise.

codeA short string identifying the specific error condition.

request_idA unique identifier for the request. Include this when contacting support.

Example error responsejson

{
  "error": {
    "message": "Invalid API key provided. Check your API key at https://www.orvexaproject.com/dashboard/api-keys.",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key",
    "request_id": "req_abc123def456"
  }
}

HTTP Status Codes

Code	Error Type	Description
400	`invalid_request_error`	The request body or parameters are invalid. Check the message field for details.
401	`authentication_error`	Authentication failed. Ensure your API key is valid and correctly formatted in the Authorization header.
403	`permission_error`	Your API key does not have permission to perform this action or access the requested resource.
404	`not_found_error`	The requested resource (model, endpoint, or workflow) does not exist.
408	`timeout_error`	The upstream model provider took too long to respond. Retry the request.
429	`rate_limit_error`	You have exceeded your rate limit or quota. Wait and retry with exponential backoff.
500	`api_error`	An internal server error occurred. This is rare — contact support with the request_id if it persists.
502	`bad_gateway_error`	The upstream model provider returned an invalid response. Retry the request.
503	`service_unavailable`	The ORVEXA service is temporarily unavailable, usually due to maintenance. Retry after a short delay.

Handling Errors

We recommend implementing robust error handling in your application, especially for rate limits and transient errors.

Always check the HTTP status code before parsing the response body.

Implement exponential backoff for 429 and 5xx errors — do not retry immediately.

Log the request_id from every error response to help with debugging and support.

Set appropriate timeouts for your HTTP client to handle 408 and 504 errors gracefully.

Retry with exponential backoffpython

import time
from openai import OpenAI, APIError, RateLimitError

client = OpenAI(
    api_key="nx-sk-dcfab6de7407c3c5f74fb627",
    base_url="https://api.orvexaproject.com/v1",
)

max_retries = 5
for attempt in range(max_retries):
    try:
        response = client.chat.completions.create(
            model="deepseek-chat",
            messages=[{"role": "user", "content": "Hello"}],
        )
        print(response.choices[0].message.content)
        break
    except RateLimitError:
        wait = 2 ** attempt
        print(f"Rate limited, retrying in {wait}s...")
        time.sleep(wait)
    except APIError as e:
        print(f"API error: {e}")
        if attempt == max_retries - 1:
            raise
        time.sleep(2 ** attempt)

Rate Limits

Rate limit information is included in the response headers of every request. Use these headers to monitor and adjust your request rate.

X-RateLimit-LimitMaximum requests per minute allowed for your plan.

X-RateLimit-RemainingNumber of requests remaining in the current rate limit window.

X-RateLimit-ResetUnix timestamp (seconds) when the rate limit window resets.