Error Reference
Error Codes
Every error returns this structure:
{"code": "AUDIO_TOO_SHORT", "message": "Audio duration is below the minimum required threshold.", "status": 400}| Code | HTTP Status | Description | Retry |
|---|---|---|---|
| UNAUTHORIZED (client error) | 401 | X-Account-ID is missing or invalid, or the credential header is missing or invalid: use X-API-Key for v2 and X-Secret-Key for v1. Verify your credentials and resubmit. | Correct and resubmit |
| INSUFFICIENT_CREDITS (client error) | 402 | No credits remaining for the account. Add credits or contact support to continue. | Add credits or contact support before resubmitting |
| NOT_FOUND (client error) | 404 | Resource not found. Returned by GET /v2/jobs/{job_id} when the job_id is invalid or the job belongs to another account; and by v1 job detail when the job_id is invalid or not found. Verify the ID and your X-Account-ID header. | Verify the ID and account; correct and resubmit |
| AUDIO_POOR_QUALITY (client error) | 422 | Recording conditions may be below the threshold used for analysis. Improve the recording environment and resubmit. | Correct and resubmit |
| AUDIO_TOO_SHORT (client error) | 400 | Recording is under 15 seconds. Submit a recording of at least 15 seconds. | Correct and resubmit |
| AUDIO_TOO_LONG (client error) | 400 | Recording exceeds the 20-minute (1200-second) maximum. Trim to 20 minutes or fewer and resubmit. | Correct and resubmit |
| UNSUPPORTED_FORMAT (client error) | 400 | Audio format is not supported. Use WAV, FLAC, MP3, or M4A. | Correct and resubmit |
| RATE_LIMIT_EXCEEDED (rate limited) | 429 | Rate limit reached. Check the Retry-After response header and retry using exponential backoff. | Retry with backoff |
| PROCESSING_ERROR (server error) | 500 | Internal processing error. Retry with the same payload using exponential backoff — no changes to the request are needed. | Retry with backoff |
Retry Guidance
For 429 and 500 responses, use exponential backoff:
- Start at 1 second.
- Double the delay on each attempt.
- Maximum 5 retries.
- For
429, check theRetry-Afterresponse header before retrying.
Other 4xx responses indicate a request condition to correct before resubmitting. For 402, add credits or contact support before resubmitting. For 404, verify the result or job ID and your account. For other codes, review the error message, adjust the request, and resubmit.