Reference
Error handling
The API uses conventional HTTP status codes. Build retries for transient failures (429 and 5xx) to keep integrations resilient.
Status codes
| Code | Name | Meaning |
|---|---|---|
| 400 | Bad Request | Invalid body schema or a missing required field (e.g. prompt). Check your payload. |
| 401 | Unauthorized | API key required: no x-api-key header was sent. |
| 402 | Payment Required | insufficient_credits: your credit balance is used up. Add credits on the Billing page. |
| 403 | Forbidden | Invalid API key: unknown, revoked, or over its per-key spend limit. |
| 429 | Too Many Requests | Rate limit or usage limit exceeded. Back off and retry per Retry-After. |
| 500 | Internal Server Error | An unexpected error occurred. Retry with backoff; check the health endpoint. |
Retrying safely
Retry 429 and 500 responses with exponential backoff and jitter. Do not retry 400, 401 or 403 — fix the request or key instead. A 402 clears once you add credits. Honor the Retry-After header when present.
python
import time, random
def with_retries(fn, max_attempts=5):
for attempt in range(max_attempts):
try:
return fn()
except Exception as err:
status = getattr(err, "status_code", None)
if status not in (429, 500) or attempt == max_attempts - 1:
raise
time.sleep(min(2 ** attempt, 30) + random.random())Troubleshooting 500s
A
500 usually indicates a transient server-side issue. Retry with backoff; if it persists, check the /health endpoint and contact support.Best practices
- Validate request bodies before sending to avoid
400s. - Set sensible timeouts and treat them like transient failures.
- Surface clear, user-friendly messages rather than raw errors in your UI.