Error Handling
When API requests fail, standardized error responses are returned.
Error Response Format
{
"error": {
"message": "Error description",
"type": "error_type",
"code": "error_code"
}
}HTTP Status Codes
| Status | Description | Recommended Action |
|---|---|---|
| 400 | Invalid request parameters | Check request format |
| 401 | Authentication failed | Verify API Key |
| 403 | Insufficient permissions | Check API Key permissions or quota |
| 404 | Resource not found | Verify model name or endpoint |
| 429 | Rate limit exceeded | Reduce request rate or upgrade plan |
| 500 | Internal server error | Retry later |
| 502 | Upstream service error | Switch channel or retry later |
| 503 | Service temporarily unavailable | Retry later |
Common Error Codes
invalid_api_key
{
"error": {
"message": "Invalid API key provided",
"type": "invalid_request_error",
"code": "invalid_api_key"
}
}Solution: Verify API Key is correct and not expired.
insufficient_quota
{
"error": {
"message": "You have exceeded your quota",
"type": "insufficient_quota",
"code": "insufficient_quota"
}
}Solution: Top up your account or upgrade your plan.
model_not_found
{
"error": {
"message": "Model not found: xxx",
"type": "invalid_request_error",
"code": "model_not_found"
}
}Solution: Verify model name is correct. Use /v1/models to get available models.
Retry Strategy
Use exponential backoff for retryable errors (429, 5xx):
- 1st retry: wait 1 second
- 2nd retry: wait 2 seconds
- 3rd retry: wait 4 seconds
- Maximum 3 retries
Python Example
import time
from openai import OpenAI, RateLimitError
client = OpenAI(base_url="https://api.fizzly.com/v1")
def call_with_retry(max_retries=3):
for i in range(max_retries):
try:
return client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Hello"}]
)
except RateLimitError:
if i < max_retries - 1:
time.sleep(2 ** i)
else:
raise