For AI agents: every API docs page in one plain-text file is at /docs/llms-full.txt, and the documentation index is at /llms.txt. This page is available as Markdown at https://diffio.ai/docs/api-reference/errors.md, and every docs URL returns Markdown when requested with Accept: text/markdown.

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.
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
400Bad request.Bad request
8 codes
| Code | Meaning | What to do |
|---|---|---|
invalid_request (400Bad request.) | The request is malformed in a way no more specific code names. | Fix: Do not retry unchanged: fix the request first. |
invalid_json (400Bad request.) | The body is not a JSON object. | Fix: Do not retry unchanged: fix the request first. |
invalid_header (400Bad request.) | A header (Idempotency-Key or Diffio-End-User) is too long. | Fix: Do not retry unchanged: fix the request first. |
invalid_parameter (400Bad request.) | A query parameter is not valid; details.parameter names it. | Fix: Do not retry unchanged: fix the request first. |
missing_field (400Bad request.) | A required body field is missing; details.field names it. | Fix: Do not retry unchanged: fix the request first. |
invalid_field (400Bad request.) | 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 (400Bad request.) | model names no Diffio model; details.models lists them. | Fix: Do not retry unchanged: fix the request first. |
usage_period_too_large (400Bad request.) | The usage period has too many generations for one report. | Fix: Ask for a shorter period. |
401Unauthorized: the API key is missing or invalid.403Forbidden: the key lacks permission.API key and permission
4 codes
| Code | Meaning | What to do |
|---|---|---|
missing_api_key (401Unauthorized: the API key is missing or invalid.) | No API key was sent. | Fix: Do not retry unchanged: fix the request first. |
invalid_api_key (401Unauthorized: the API key is missing or invalid.) | The API key is not valid. | Fix: Do not retry unchanged: fix the request first. |
unauthenticated (401Unauthorized: the API key is missing or invalid.) | The request could not be authenticated. | Fix: Do not retry unchanged: fix the request first. |
permission_denied (403Forbidden: the key lacks permission.) | 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. |
402Payment required: see error.code for the billing problem.Billing
5 codes
| Code | Meaning | What to do |
|---|---|---|
payment_required (402Payment required: see error.code for the billing problem.) | The account cannot start this work. | Pay: Retry once the account can pay (add credit or a payment method in the dashboard). |
insufficient_credit (402Payment required: see error.code for the billing problem.) | 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 (402Payment required: see error.code for the billing problem.) | The account reached the monthly usage limit it set. | Pay: Retry after raising the limit, or next month. |
payment_failed (402Payment required: see error.code for the billing problem.) | 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 (402Payment required: see error.code for the billing problem.) | 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). |
404Not found.405Client error.Not found and wrong method
9 codes
| Code | Meaning | What to do |
|---|---|---|
not_found (404Not found.) | What the path names does not exist. | Fix: Do not retry unchanged: fix the request first. |
route_not_found (404Not found.) | No version-two route has that path. | Fix: Do not retry unchanged: fix the request first. |
project_not_found (404Not found.) | 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 (404Not found.) | No generation of the project has that id. | Fix: Do not retry unchanged: fix the request first. |
export_not_found (404Not found.) | No export of the generation has that id. | Fix: Do not retry unchanged: fix the request first. |
share_not_found (404Not found.) | No share has that id, or it was revoked. | Stop: Do not retry: this will not change. |
transcript_not_found (404Not found.) | 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 (404Not found.) | No assistant turn has that id. | Fix: Do not retry unchanged: fix the request first. |
method_not_allowed (405Client error.) | The route does not take this method; Allow names those it does. | Fix: Do not retry unchanged: fix the request first. |
409Conflict: see error.code for which one.State conflicts
14 codes
| Code | Meaning | What to do |
|---|---|---|
conflict (409Conflict: see error.code for which one.) | 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 (409Conflict: see error.code for which one.) | 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 (409Conflict: see error.code for which one.) | The Idempotency-Key was used for a different request. | Fix: Use a new key for a different request. |
not_ready (409Conflict: see error.code for which one.) | 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 (409Conflict: see error.code for which one.) | 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 (409Conflict: see error.code for which one.) | 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 (409Conflict: see error.code for which one.) | Four exports of this generation are already rendering. | Retry: Retry once one of them finishes. |
leveling_not_available (409Conflict: see error.code for which one.) | Leveling cannot be applied to this generation. | Fix: Retry without leveling. |
video_not_available (409Conflict: see error.code for which one.) | An mp4 was asked for and the project has no video. | Fix: Retry with an audio format. |
generation_in_progress (409Conflict: see error.code for which one.) | A generation of the project is still running; details.generation_ids names them. | Retry: Retry once they finish. |
upload_already_received (409Conflict: see error.code for which one.) | The project's file has already been uploaded. | Stop: Do not retry: this will not change. |
upload_missing (409Conflict: see error.code for which one.) | The upload has not completed yet. | Fix: Finish the upload, then retry. |
project_exists (409Conflict: see error.code for which one.) | A project with that id already exists. | Fix: Read the resource again, then retry with what it now says. |
generation_unavailable (409Conflict: see error.code for which one.) | The project or the API key was removed while it ran. | Stop: Do not retry: this will not change. |
413Payload too large.415Client error.422Unprocessable request.Content
5 codes
| Code | Meaning | What to do |
|---|---|---|
payload_too_large (413Payload too large.) | The request is too large. | Fix: Do not retry unchanged: fix the request first. |
upload_too_large (413Payload too large.) | The file is larger than the upload limit. | Fix: Do not retry unchanged: fix the request first. |
transcript_draft_too_large (413Payload too large.) | A draft's data is over 900,000 bytes as JSON. | Fix: Do not retry unchanged: fix the request first. |
unsupported_media_type (415Client error.) | The file type cannot be restored. | Fix: Do not retry unchanged: fix the request first. |
transcript_unreadable (422Unprocessable request.) | The generation's stored transcript cannot be read. | Stop: Do not retry: this will not change. |
429Too many requests.Rate limits
1 code
| Code | Meaning | What to do |
|---|---|---|
rate_limited (429Too many requests.) | Too many requests of this kind in a short time. | Retry: Retry later, backing off. |
5xxDiffio's side
5 codes
| Code | Meaning | What to do |
|---|---|---|
internal_error (500Server error.502Bad gateway.) | Diffio could not complete the request. | Retry: Retry with exponential backoff; quote request_id if it keeps happening. |
generation_start_failed (500Server error.) | The generation was created but could not be started. | Retry: Retry with exponential backoff; quote request_id if it keeps happening. |
unavailable (503Service unavailable.) | A service the request needs is unavailable. | Retry: Retry with exponential backoff; quote request_id if it keeps happening. |
edit_not_queued (503Service unavailable.) | The edit could not be queued; nothing was billed. | Retry: Retry the same request shortly (after a second or more, backing off). |
assistant_unavailable (503Service unavailable.) | The edit assistant is unavailable. | Retry: Retry with exponential backoff; quote request_id if it keeps happening. |
Failed generation
21 codes
| 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
2 codes
| 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
1 code
| 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
9 codes
| 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).