Errors

Error object shape, codes, and HTTP status mapping.

Every error returns this structure:

{"code": "AUDIO_TOO_SHORT", "message": "Audio duration is below the minimum required threshold.", "status": 400}

Field	Type	Description
`code`	string	Machine-readable error code. See Error codes.
`message`	string	Human-readable description of the condition.
`status`	integer	HTTP status code of the response.

Error codes

Code	HTTP status	Description	Retry
`UNAUTHORIZED`	401	`X-Account-ID` is missing or invalid, or the `X-API-Key` credential header is missing or invalid. Verify your credentials and resubmit.	Correct and resubmit
`INSUFFICIENT_CREDITS`	402	No credits remaining for the account. Add credits or contact support to continue.	Add credits or contact support before resubmitting
`NOT_FOUND`	404	Unknown or cross-account resource: a `job_id`, `model_name`, `sign_name`, or `group_id` that does not exist for this account. Verify the ID and your `X-Account-ID` header.	Verify the ID and account; correct and resubmit
`AUDIO_POOR_QUALITY`	422	Recording conditions may be below the threshold used for analysis. Improve the recording environment and resubmit.	Correct and resubmit
`AUDIO_TOO_SHORT`	400	Recording is under 15 seconds. Submit a recording of at least 15 seconds.	Correct and resubmit
`AUDIO_TOO_LONG`	400	Recording exceeds the 20-minute (1200-second) maximum. Trim to 20 minutes or fewer and resubmit.	Correct and resubmit
`UNSUPPORTED_FORMAT`	400	Audio format is not supported. Use WAV, FLAC, MP3, or M4A.	Correct and resubmit
`RATE_LIMIT_EXCEEDED`	429	Rate limit reached. Check the `Retry-After` response header and retry using exponential backoff.	Retry with backoff
`PROCESSING_ERROR`	500	Internal processing error. Retry with the same payload using exponential backoff — no changes to the request are needed.	Retry with backoff

For the audio conditions behind AUDIO_POOR_QUALITY, AUDIO_TOO_SHORT, AUDIO_TOO_LONG, and UNSUPPORTED_FORMAT, see Audio Requirements. For account rate limits and the Retry-After header, see API Reference.

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 the Retry-After response header before retrying.

Other 4xx: fix the request, then resubmit. 402: add credits or contact support. 404: check the resource ID and X-Account-ID. Otherwise use message.

A job that ends with status: "failed" or status: "timed-out" is not an error response — GET /v2/jobs/{job_id} returns 200 OK with the job object. See Job status: failed.