Error Codes
Common error codes and how to handle them.
All API errors return a JSON body with an error object. Use the HTTP status code and the error.code field to determine what went wrong.
Error Response Format
{
"error": {
"message": "Rate limit exceeded. Please slow down.",
"type": "rate_limit_error",
"code": "rate_limit_exceeded"
}
}Error Code Reference
| Code | Meaning | How to Fix |
|---|---|---|
| 400 | Bad Request | Check request body format and required fields. |
| 401 | Unauthorized | Check that your API key is valid and included in the Authorization header. |
| 402 | Insufficient Credits | Top up credits in the Dashboard. |
| 404 | Not Found | Check the endpoint URL and any resource IDs. |
| 410 | Gone | Resource has expired (e.g., an image generation task older than 30 days). |
| 429 | Rate Limited | Slow down requests and implement backoff. See Rate Limits. |
| 500 | Server Error | Retry after a moment. Contact support if the issue persists. |
Retry Strategy
Not all errors are retryable. Here is a quick guide:
| Code | Retryable? | Notes |
|---|---|---|
| 400 | No | Fix the request before retrying. |
| 401 | No | Fix your API key or authentication. |
| 402 | No | Add credits, then retry. |
| 404 | No | Fix the URL or resource ID. |
| 410 | No | The resource is permanently gone. |
| 429 | Yes | Wait for the Retry-After header duration. |
| 500 | Yes | Use exponential backoff. |
Exponential Backoff
For retryable errors, use exponential backoff to avoid overwhelming the API:
async function requestWithRetry(fn, maxRetries = 5) {
for (let attempt = 0; attempt <= maxRetries; attempt++) {
const response = await fn();
if (response.ok) return response;
// Only retry on 429 or 5xx
if (response.status !== 429 && response.status < 500) {
throw new Error(`Request failed with status ${response.status}`);
}
if (attempt < maxRetries) {
const backoff = Math.min(1000 * 2 ** attempt, 30000);
const jitter = Math.random() * 1000;
await new Promise((r) => setTimeout(r, backoff + jitter));
}
}
throw new Error("Max retries exceeded");
}Always add random jitter to your backoff delay. This prevents many clients from retrying at exactly the same moment.