---
title: Errors
description: Error object shape, codes, and HTTP status mapping.
type: doc
icon: circle-alert
sidebar:
  label: Errors
  order: 4
  icon: circle-alert
search:
  tags: [results]
---
Every error returns this structure:

```json
{"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](#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](/guides/audio-requirements). For account rate limits and the `Retry-After` header, see [API Reference](/reference#rate-limits).

## 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](/reference/response-schema#job-status-failed).