Error Handling

This guide covers the OfoxAI API error response format, common error scenarios, and recommended handling strategies.

Error Response Format

All error responses follow a unified JSON format:


{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API Key is invalid. Please check and try again.",
    "type": "authentication_error"
  }
}

HTTP Status Codes

Status Code	Type	Description	Should Retry?
`400`	`invalid_request_error`	Invalid request parameters	❌ Fix parameters and retry
`401`	`authentication_error`	Invalid or missing API Key	❌ Check API Key
`403`	`permission_error`	Insufficient permissions	❌ Check account permissions
`404`	`not_found_error`	Model or resource not found	❌ Check model ID
`429`	`rate_limit_error`	Rate limit exceeded	✅ Wait and retry
`500`	`internal_error`	Internal server error	✅ Retry later
`502`	`upstream_error`	Upstream provider error	✅ Switch model or retry
`503`	`service_unavailable`	Service temporarily unavailable	✅ Retry later

Common Errors and Solutions

401 — Invalid API Key


{"error": {"code": "invalid_api_key", "message": "The API key provided is invalid."}}

Solutions:

Verify the API Key was copied correctly (including the sk- prefix)
Confirm the Key hasn’t expired or been disabled
Check that environment variables are loaded correctly

429 — Rate Limited


{"error": {"code": "rate_limit_exceeded", "message": "Rate limit reached. Please retry after 1s."}}

Solutions:

Check the x-ratelimit-reset-requests header in the response
Implement exponential backoff retries
Contact support for a higher quota if needed

502 — Upstream Error


{"error": {"code": "upstream_error", "message": "The upstream provider returned an error."}}

Solutions:

Use Fallback to automatically switch to alternative models
Retry later
Check the model provider’s status page

Retry Strategy

We recommend using Exponential Backoff:

retry.py


import time
import random
from openai import OpenAI, APIError, RateLimitError, APIConnectionError
 
client = OpenAI(
    base_url="https://api.ofox.ai/v1",
    api_key="<your OFOXAI_API_KEY>"
)
 
def chat_with_retry(max_retries=5, **kwargs):
    """Retry wrapper with exponential backoff"""
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(**kwargs)
 
        except RateLimitError:
            # 429: wait and retry
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f"Rate limited, retrying in {wait:.1f}s...")
            time.sleep(wait)
 
        except APIConnectionError:
            # Network error: wait briefly and retry
            wait = 2 ** attempt
            print(f"Connection error, retrying in {wait}s...")
            time.sleep(wait)
 
        except APIError as e:
            if e.status_code and e.status_code >= 500:
                # 5xx: server error, retry
                wait = 2 ** attempt
                time.sleep(wait)
            else:
                # 4xx: client error, don't retry
                raise
 
    raise Exception(f"Failed after {max_retries} retries")
 
# Usage
response = chat_with_retry(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)

Timeout Settings

We recommend setting reasonable timeouts for API calls:


# Python OpenAI SDK
client = OpenAI(
    base_url="https://api.ofox.ai/v1",
    api_key="<your OFOXAI_API_KEY>",
    timeout=60.0,  # 60 second timeout
    max_retries=3  # SDK built-in retry
)


// TypeScript OpenAI SDK
const client = new OpenAI({
  baseURL: 'https://api.ofox.ai/v1',
  apiKey: '<your OFOXAI_API_KEY>',
  timeout: 60000,  // 60 second timeout
  maxRetries: 3    // SDK built-in retry
})

For streaming requests, use a longer timeout (120-300 seconds), as the model may need more time to generate the complete response.

Best Practices

Distinguish retryable from non-retryable errors — 4xx usually requires fixing the request; 5xx can be retried
Use exponential backoff — Avoid frequent retries during rate limiting
Set a maximum retry count — Prevent infinite retries
Log errors — Facilitate troubleshooting
Configure fallbacks — Use OfoxAI’s provider.fallback parameter to automatically switch models
Monitor error rates — Watch error trends in the console