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
`INVALID_MODEL_VERSION`	400	`model_version` is not in `X.Y.Z` form: digits only, three parts, no `v` prefix, no spaces. `message`: `model_version must match X.Y.Z (e.g. 2.0.0)`.	Correct and resubmit
`UNKNOWN_MODEL_VERSION`	400	`model_version` is well formed but is not an available version. The `message` lists the available versions: `unknown model_version; available: 2.0.0, 2.1.0`.	Resubmit with an available version, or omit the field
`GROUP_VERSION_MISMATCH`	400	A group call used a version other than the group’s. A group’s model version is fixed when the group is created. Either a group analyze call (`.../groups/{group_id}/analyze` or `.../analyze/longitudinal`) sent a `model_version` that differs from the group’s, `message`: `model_version does not match the group's model version; the group runs <version>`; or `POST /v2/groups/{group_id}/jobs` named jobs that ran on a different version, `message`: `model_version does not match the group's model version; jobs: <job_id>, <job_id>`.	Omit `model_version`, or send the group’s version; remove the listed jobs from the request
`GROUP_UNSUPPORTED_MODEL_VERSION`	400	Deprecated. No longer returned; group calls return `GROUP_VERSION_MISMATCH`. The name stays reserved for one more release.	None
`PARAM_REQUIRES_MODEL_VERSION`	400	`provided_age` or `provided_sex` was sent on a request that runs `2.0.0`. The `message` names the fields and the version to use: `parameter requires a newer model_version: provided_age needs 2.1.0 or later; this request used 2.0.0 (the default)`.	Send `model_version=2.1.0` with the fields, or omit the fields
`INVALID_PROVIDED_AGE`	400	`provided_age` is not a number from `0` to `130`. `message`: `invalid provided_age: must be a number from 0 to 130`.	Correct and resubmit
`INVALID_PROVIDED_SEX`	400	`provided_sex` is not exactly `female` or `male`, in lowercase. `message`: `invalid provided_sex: must be female or male`.	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 the model_version and speaker-field codes, see Model versions. 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.