> For the complete documentation index, see [llms.txt](https://diffio.ai/llms.txt). This page is also available as HTML at https://diffio.ai/docs/api-reference/errors/.

# Errors: every API error code and what to do

Every error carries a stable `error.code` to branch on. This page lists all 84 codes from the API's error catalogue, with what to do about each.

**Where error codes appear**

Refused request:

`4xx` `5xx`

```
{"error": {
  "code": "not_ready",
  "message": "...",
  "request_id": "..."
}}
```

The answer to your call. Quote `request_id` to support.

Failed resource:

`"status": "failed"`

```
{"status": "failed",
 "error": {
  "code": "no_speech_detected",
  "message": "..."
}}
```

On a generation, project, export or assistant turn, read later (or sent by webhook).

## What to do

- Retry: Retry later with backoff, or make a new resource. (30 codes)
- Fix: Change the request (body, header, key or id) first. (30 codes)
- Pay: Add credit or a payment method, then retry. (9 codes)
- Stop: Will not change: do not retry. (15 codes)

Both SDKs retry calls that are safe to repeat after `408`, `429`, `5xx` and network errors, with exponential backoff and `Retry-After`. A refusal they give up on raises `DiffioApiError` with `status`, `code`, `request_id` and `details`.

## Error codes

`400`

### Bad request

| Code | Meaning | What to do |
| --- | --- | --- |
| `invalid_request` (`400`) | The request is malformed in a way no more specific code names. | Fix: Do not retry unchanged: fix the request first. |
| `invalid_json` (`400`) | The body is not a JSON object. | Fix: Do not retry unchanged: fix the request first. |
| `invalid_header` (`400`) | A header (`Idempotency-Key` or `Diffio-End-User`) is too long. | Fix: Do not retry unchanged: fix the request first. |
| `invalid_parameter` (`400`) | A query parameter is not valid; `details.parameter` names it. | Fix: Do not retry unchanged: fix the request first. |
| `missing_field` (`400`) | A required body field is missing; `details.field` names it. | Fix: Do not retry unchanged: fix the request first. |
| `invalid_field` (`400`) | A body field is not valid, `details.field` names it when it is one field (for an edit, words that change nothing are `invalid_field` with field words). | Fix: Do not retry unchanged: fix the request first. |
| `unknown_model` (`400`) | model names no Diffio model; `details.models` lists them. | Fix: Do not retry unchanged: fix the request first. |
| `usage_period_too_large` (`400`) | The usage period has too many generations for one report. | Fix: Ask for a shorter period. |

`401` `403`

### API key and permission

| Code | Meaning | What to do |
| --- | --- | --- |
| `missing_api_key` (`401`) | No API key was sent. | Fix: Do not retry unchanged: fix the request first. |
| `invalid_api_key` (`401`) | The API key is not valid. | Fix: Do not retry unchanged: fix the request first. |
| `unauthenticated` (`401`) | The request could not be authenticated. | Fix: Do not retry unchanged: fix the request first. |
| `permission_denied` (`403`) | The key is not active, or lacks the scope or the read or write permission this route needs. | Fix: Do not retry with this key: use a key with the right scope. |

`402`

### Billing

| Code | Meaning | What to do |
| --- | --- | --- |
| `payment_required` (`402`) | The account cannot start this work. | Pay: Retry once the account can pay (add credit or a payment method in the dashboard). |
| `insufficient_credit` (`402`) | The prepaid balance does not cover the most this could bill. | Pay: Retry once the account can pay (add credit or a payment method in the dashboard). |
| `usage_limit_reached` (`402`) | The account reached the monthly usage limit it set. | Pay: Retry after raising the limit, or next month. |
| `payment_failed` (`402`) | The account's last payment failed. | Pay: Retry once the account can pay (add credit or a payment method in the dashboard). |
| `needs_payment_method` (`402`) | The free credit is used up and the account has no card. | Pay: Retry once the account can pay (add credit or a payment method in the dashboard). |

`404` `405`

### Not found and wrong method

| Code | Meaning | What to do |
| --- | --- | --- |
| `not_found` (`404`) | What the path names does not exist. | Fix: Do not retry unchanged: fix the request first. |
| `route_not_found` (`404`) | No version-two route has that path. | Fix: Do not retry unchanged: fix the request first. |
| `project_not_found` (`404`) | No project of this account (and end user, with `Diffio-End-User`) has that id. | Fix: Do not retry unchanged: fix the request first. |
| `generation_not_found` (`404`) | No generation of the project has that id. | Fix: Do not retry unchanged: fix the request first. |
| `export_not_found` (`404`) | No export of the generation has that id. | Fix: Do not retry unchanged: fix the request first. |
| `share_not_found` (`404`) | No share has that id, or it was revoked. | Stop: Do not retry: this will not change. |
| `transcript_not_found` (`404`) | A finished generation has no stored transcript (results made before transcripts were kept). | Stop: Do not retry: this will not change. |
| `transcript_assistant_turn_not_found` (`404`) | No assistant turn has that id. | Fix: Do not retry unchanged: fix the request first. |
| `method_not_allowed` (`405`) | The route does not take this method; Allow names those it does. | Fix: Do not retry unchanged: fix the request first. |

`409`

### State conflicts

| Code | Meaning | What to do |
| --- | --- | --- |
| `conflict` (`409`) | Another request changed or revoked the same share at the same time, and the later one won. | Fix: Read the resource again, then retry with what it now says. |
| `revision_conflict` (`409`) | A save named a revision that is no longer current; `details.current_revision` is the current one. | Fix: Read the resource again, then retry with what it now says. |
| `idempotency_key_conflict` (`409`) | The `Idempotency-Key` was used for a different request. | Fix: Use a new key for a different request. |
| `not_ready` (`409`) | Not yet: what the request needs is still being made (a generation still running, separated tracks or a transcript still being prepared). `details.generation_status` or `details.transcription_status` says which. | Retry: Retry the same request shortly (after a second or more, backing off). |
| `not_available` (`409`) | Never, for this resource: it failed, it will never have what the request needs, or its project is being deleted. `details.transcription_status` says the transcript's state where it matters. | Stop: Do not retry: this will not change. |
| `not_editable` (`409`) | This result's transcript cannot be edited: it is not a finished Pro result that kept what an edit needs, or shortening (tighten) was asked of a video project. | Stop: Do not retry: this will not change. |
| `too_many_exports` (`409`) | Four exports of this generation are already rendering. | Retry: Retry once one of them finishes. |
| `leveling_not_available` (`409`) | Leveling cannot be applied to this generation. | Fix: Retry without leveling. |
| `video_not_available` (`409`) | An mp4 was asked for and the project has no video. | Fix: Retry with an audio format. |
| `generation_in_progress` (`409`) | A generation of the project is still running; `details.generation_ids` names them. | Retry: Retry once they finish. |
| `upload_already_received` (`409`) | The project's file has already been uploaded. | Stop: Do not retry: this will not change. |
| `upload_missing` (`409`) | The upload has not completed yet. | Fix: Finish the upload, then retry. |
| `project_exists` (`409`) | A project with that id already exists. | Fix: Read the resource again, then retry with what it now says. |
| `generation_unavailable` (`409`) | The project or the API key was removed while it ran. | Stop: Do not retry: this will not change. |

`413` `415` `422`

### Content

| Code | Meaning | What to do |
| --- | --- | --- |
| `payload_too_large` (`413`) | The request is too large. | Fix: Do not retry unchanged: fix the request first. |
| `upload_too_large` (`413`) | The file is larger than the upload limit. | Fix: Do not retry unchanged: fix the request first. |
| `transcript_draft_too_large` (`413`) | A draft's data is over 900,000 bytes as JSON. | Fix: Do not retry unchanged: fix the request first. |
| `unsupported_media_type` (`415`) | The file type cannot be restored. | Fix: Do not retry unchanged: fix the request first. |
| `transcript_unreadable` (`422`) | The generation's stored transcript cannot be read. | Stop: Do not retry: this will not change. |

`429`

### Rate limits

| Code | Meaning | What to do |
| --- | --- | --- |
| `rate_limited` (`429`) | Too many requests of this kind in a short time. | Retry: Retry later, backing off. |

`5xx`

### Diffio's side

| Code | Meaning | What to do |
| --- | --- | --- |
| `internal_error` (`500` `502`) | Diffio could not complete the request. | Retry: Retry with exponential backoff; quote `request_id` if it keeps happening. |
| `generation_start_failed` (`500`) | The generation was created but could not be started. | Retry: Retry with exponential backoff; quote `request_id` if it keeps happening. |
| `unavailable` (`503`) | A service the request needs is unavailable. | Retry: Retry with exponential backoff; quote `request_id` if it keeps happening. |
| `edit_not_queued` (`503`) | The edit could not be queued; nothing was billed. | Retry: Retry the same request shortly (after a second or more, backing off). |
| `assistant_unavailable` (`503`) | The edit assistant is unavailable. | Retry: Retry with exponential backoff; quote `request_id` if it keeps happening. |

### Failed generation

| Code | Meaning | What to do |
| --- | --- | --- |
| `restoration_failed` | Restoring the audio failed. | Retry: Create a new generation. |
| `no_speech_detected` | No speech was heard in the recording. | Stop: Do not retry this file: it has no speech to restore. |
| `media_too_long` | The recording is longer than the length limit. | Stop: Do not retry this file: upload a shorter one. |
| `transcription_failed` | Transcribing the recording failed on Diffio's side. | Retry: Create a new generation (`error.retryable` is true). |
| `cancelled` | The generation was cancelled. | Retry: Create a new generation. |
| `timed_out` | The generation did not finish in the time allowed. | Retry: Create a new generation. |
| `invalid_input` | The recording could not be read as it is. | Stop: Do not retry this file: export the recording again. |
| `edit_not_queued` | The transcript edit could not be queued. | Retry: Send the edit again (`edited_transcript` in a playback grant holds its words). |
| `upload_missing` | The project's upload never arrived. | Retry: Upload the file again (`POST .../upload)`, then create a new generation. |
| `preprocessing_failed` | The upload could not be prepared. | Stop: Do not retry this file: upload another export of it. |
| `needs_payment_method` | The account had no card once the recording's length was known. | Pay: Retry once the account can pay (add credit or a payment method in the dashboard). |
| `insufficient_credit` | The prepaid balance did not cover the recording. | Pay: Retry once the account can pay (add credit or a payment method in the dashboard). |
| `usage_limit_reached` | The account reached its monthly usage limit. | Pay: Create a new generation after raising the limit. |
| `payment_failed` | The account's last payment failed. | Pay: Retry once the account can pay (add credit or a payment method in the dashboard). |
| `expired` | The generation waited too long to start. | Retry: Create a new generation. |
| `restored_video_failed` | Making the restored video (mp4) failed. | Retry: Create a new generation. |
| `generation_invalid` | The generation's request could not be started. | Retry: Create a new generation. |
| `unsupported_model` | The model the generation named is not served. | Retry: Create a new generation with a model from `GET /v2/models`. |
| `job_missing` | The generation's job was lost before it started. | Retry: Create a new generation. |
| `start_failed` | The generation could not be started. | Retry: Create a new generation. |
| `generation_failed` | The generation failed for another reason. | Retry: Create a new generation; quote its id if it keeps happening. |

### Failed project

| Code | Meaning | What to do |
| --- | --- | --- |
| `media_processing_failed` | The upload could not be prepared. | Retry: Create a new project with another export of the recording. |
| `project_failed` | The project failed for another reason. | Retry: Create a new project. |

### Failed export

| Code | Meaning | What to do |
| --- | --- | --- |
| `export_failed` | Rendering the export failed. | Retry: Ask for the export again (`POST .../exports` renders it again). |

### Failed assistant turn

| Code | Meaning | What to do |
| --- | --- | --- |
| `rate_limited` | Too many assistant requests in a few minutes, or a day's worth of use. | Retry: Ask again later. |
| `assistant_timeout` | The assistant did not finish the turn. | Retry: Ask again, perhaps something narrower. |
| `assistant_unavailable` | The assistant is unavailable. | Retry: Ask again shortly. |
| `not_editable` | The result stopped being editable while the turn ran. | Stop: Do not retry: this will not change. |
| `invalid_field` | The assistant could not read the request. | Stop: Do not retry unchanged: fix the request first. |
| `permission_denied` | The account may not use the assistant. | Stop: Do not retry: this will not change. |
| `unauthenticated` | The turn's owner could not be named. | Retry: Ask again. |
| `project_not_found` | The project went away while the turn ran. | Stop: Do not retry: this will not change. |
| `internal_error` | The turn failed on Diffio's side. | Retry: Ask again. |

The same table is in the OpenAPI document as `x-error-codes` on the `Error` and `ResourceError` schemas (`GET https://api.diffio.ai/v2/openapi.json`).

## Related pages

- [API reference introduction](https://diffio.ai/docs/api-reference/introduction/): The error shape, base URL, authentication and request conventions.
- [Billing](https://diffio.ai/docs/overview/administration/billing/): What the 402 codes mean for credit and card billing.
- [Get a generation](https://diffio.ai/docs/api-reference/get-generation/): Where a failed generation reports its error.
- [Webhooks](https://diffio.ai/docs/developers/webhooks/): The failed events that carry a resource error.
