Error Handling

Error codes, response format, and retry strategies

Error Response Format#

All errors return a JSON object with the following structure:

{
  "error": {
    "message": "Human-readable error description",
    "type": "error_type",
    "code": "error_code"
  }
}

HTTP Status Codes#

Code	Meaning	Common Cause
`400`	Bad Request	Invalid request body or parameters
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Key not subscribed to the requested model
`404`	Not Found	Model or endpoint not found
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Gateway error
`502`	Bad Gateway	Upstream provider error
`503`	Service Unavailable	Provider temporarily unavailable

Retry Strategy#

For 429 and 5xx errors, implement exponential backoff with jitter. Start at 1 second and double each retry, up to a maximum of 60 seconds.

Python

import time
import random
from openai import OpenAI, APIError, RateLimitError
 
client = OpenAI(base_url="https://api.foza.ai/v1", api_key="sk-foza-xxxxx")
 
def call_with_retry(max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="openai/gpt-4o",
                messages=[{"role": "user", "content": "Hello"}],
            )
        except RateLimitError:
            wait = (2 ** attempt) + random.random()
            print(f"Rate limited, retrying in {wait:.1f}s...")
            time.sleep(wait)
        except APIError as e:
            if e.status_code and e.status_code >= 500:
                wait = (2 ** attempt) + random.random()
                time.sleep(wait)
            else:
                raise
    raise Exception("Max retries exceeded")

Common Errors#

401 Unauthorized#

Your API key is missing, invalid, or deactivated. Check that:

The Authorization header is set correctly
The key starts with sk-foza-
The key has not been deactivated in the console

403 Forbidden#

Your key is valid but not subscribed to the requested model. Go to Console → Marketplace and subscribe the model to your key.

429 Rate Limit#

The provider has a per-second request limit. Wait and retry with exponential backoff.

Streaming

Claude Code