# Error Handling — API Error Codes & Retry Strategies

Source: https://ofox.io/docs/develop/guides/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:

```json
{
  "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

```json
{"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

```json
{"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

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

**Solutions**:
- Use [Fallback](https://ofox.io/docs/develop/advanced/fallback) to automatically switch to alternative models
- Retry later
- Check the model provider's status page

## Retry Strategy

We recommend using **Exponential Backoff**:

```python filename="retry.py" showLineNumbers
import time
import random
from openai import OpenAI, APIError, RateLimitError, APIConnectionError

client = OpenAI(
    base_url="https://api.ofox.io/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-6.1-sol",
    messages=[{"role": "user", "content": "Hello"}]
)
```

## Timeout Settings

We recommend setting reasonable timeouts for API calls:

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

```typescript
// TypeScript OpenAI SDK
const client = new OpenAI({
  baseURL: 'https://api.ofox.io/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

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