Error Handling
Understanding API error codes and how to handle them.
Error Response Format
All errors follow a consistent format:
{
"error": {
"code": "invalid_request",
"message": "The 'message' field is required.",
"param": "message"
},
"meta": {
"request_id": "req_abc123"
}
}HTTP Status Codes
| Status | Description |
|---|---|
200 | Success |
400 | Bad Request — Invalid parameters |
401 | Unauthorized — Invalid or missing API key |
403 | Forbidden — Insufficient permissions |
404 | Not Found — Resource doesn't exist |
429 | Too Many Requests — Rate limit exceeded |
500 | Internal Server Error — Something went wrong |
Error Codes
| Code | Status | Description |
|---|---|---|
invalid_request | 400 | Request body is malformed or missing required fields |
invalid_api_key | 401 | API key is invalid or expired |
insufficient_permissions | 403 | API key lacks required permissions |
not_found | 404 | The requested resource was not found |
rate_limit_exceeded | 429 | Too many requests in a given time period |
internal_error | 500 | An unexpected error occurred |
Retry Strategy
For 429 and 5xx errors, implement exponential backoff:
async function fetchWithRetry(url, options, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
const response = await fetch(url, options);
if (response.ok) return response;
if (response.status === 429 || response.status >= 500) {
const delay = Math.pow(2, i) * 1000;
await new Promise(r => setTimeout(r, delay));
continue;
}
throw new Error(`API error: ${response.status}`);
}
throw new Error('Max retries exceeded');
}