Skip to content

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.

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

400Bad request.

Bad request

8 codes
CodeMeaningWhat 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
CodeMeaningWhat 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
CodeMeaningWhat 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
CodeMeaningWhat 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
CodeMeaningWhat 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
CodeMeaningWhat 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
CodeMeaningWhat to do
rate_limited (429Too many requests.)Too many requests of this kind in a short time.Retry: Retry later, backing off.
5xx

Diffio's side

5 codes
CodeMeaningWhat 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
CodeMeaningWhat to do
restoration_failedRestoring the audio failed.Retry: Create a new generation.
no_speech_detectedNo speech was heard in the recording.Stop: Do not retry this file: it has no speech to restore.
media_too_longThe recording is longer than the length limit.Stop: Do not retry this file: upload a shorter one.
transcription_failedTranscribing the recording failed on Diffio's side.Retry: Create a new generation (error.retryable is true).
cancelledThe generation was cancelled.Retry: Create a new generation.
timed_outThe generation did not finish in the time allowed.Retry: Create a new generation.
invalid_inputThe recording could not be read as it is.Stop: Do not retry this file: export the recording again.
edit_not_queuedThe transcript edit could not be queued.Retry: Send the edit again (edited_transcript in a playback grant holds its words).
upload_missingThe project's upload never arrived.Retry: Upload the file again (POST .../upload), then create a new generation.
preprocessing_failedThe upload could not be prepared.Stop: Do not retry this file: upload another export of it.
needs_payment_methodThe 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_creditThe 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_reachedThe account reached its monthly usage limit.Pay: Create a new generation after raising the limit.
payment_failedThe account's last payment failed.Pay: Retry once the account can pay (add credit or a payment method in the dashboard).
expiredThe generation waited too long to start.Retry: Create a new generation.
restored_video_failedMaking the restored video (mp4) failed.Retry: Create a new generation.
generation_invalidThe generation's request could not be started.Retry: Create a new generation.
unsupported_modelThe model the generation named is not served.Retry: Create a new generation with a model from GET /v2/models.
job_missingThe generation's job was lost before it started.Retry: Create a new generation.
start_failedThe generation could not be started.Retry: Create a new generation.
generation_failedThe generation failed for another reason.Retry: Create a new generation; quote its id if it keeps happening.

Failed project

2 codes
CodeMeaningWhat to do
media_processing_failedThe upload could not be prepared.Retry: Create a new project with another export of the recording.
project_failedThe project failed for another reason.Retry: Create a new project.

Failed export

1 code
CodeMeaningWhat to do
export_failedRendering the export failed.Retry: Ask for the export again (POST .../exports renders it again).

Failed assistant turn

9 codes
CodeMeaningWhat to do
rate_limitedToo many assistant requests in a few minutes, or a day's worth of use.Retry: Ask again later.
assistant_timeoutThe assistant did not finish the turn.Retry: Ask again, perhaps something narrower.
assistant_unavailableThe assistant is unavailable.Retry: Ask again shortly.
not_editableThe result stopped being editable while the turn ran.Stop: Do not retry: this will not change.
invalid_fieldThe assistant could not read the request.Stop: Do not retry unchanged: fix the request first.
permission_deniedThe account may not use the assistant.Stop: Do not retry: this will not change.
unauthenticatedThe turn's owner could not be named.Retry: Ask again.
project_not_foundThe project went away while the turn ran.Stop: Do not retry: this will not change.
internal_errorThe 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).

Report an issue with this page