Error Handling
The API uses standard HTTP status codes. Error responses include a JSON body with adetail field.
Error Response Format
{
"detail": "Human-readable error message"
}Status Codes
| Code | Meaning | What to do |
|---|---|---|
| 200 | Success | Request completed successfully |
| 400 | Bad Request | Check request body format and required fields |
| 401 | Unauthorized | Check your API token is valid and included in headers |
| 403 | Forbidden | Token revoked or email not verified |
| 413 | Payload Too Large | Audio file or text exceeds size limits for your tier |
| 429 | Too Many Requests | Rate limit or quota exceeded. Wait or upgrade tier |
| 500 | Internal Server Error | Retry after a brief pause. Contact support if persistent |
| 503 | Service Unavailable | Model is loading or at capacity. Retry with exponential backoff |
Retry Strategy
429 responses: Wait until the next day (daily cap) or next month (monthly volume) resets.
500/503 responses: Retry with exponential backoff (1s, 2s, 4s). Max 3 retries.
400/401/403 responses: Do not retry. Fix the request.