Concept

Errors

Handle the stable error envelope, HTTP status codes, and failed jobs.

Immediate error envelope

{
  "error": {
    "code": "daily_limit_reached",
    "message": "You've reached your daily upload limit."
  }
}

Use error.code for program logic and error.message for a safe user-facing explanation.

HTTP statuses

Status	Codes	Meaning
400	`invalid_request / invalid_source / invalid_source_url / invalid_limit / invalid_upload / empty_upload / invalid_multipart_upload / invalid_multipart_parts`	Malformed JSON, source selection, URL, limit, upload, or multipart fields.
401	`missing_api_key / invalid_api_key`	Bearer authentication is absent or invalid.
403	`pro_required / upload_not_owned`	A plan-only feature was requested or the object belongs to another account.
404	`upload_not_found / not_found`	The uploaded object or account-scoped job does not exist.
413	`file_too_large`	The stored or declared media is above the account limit.
415	`unsupported_type`	The file extension or MIME type is not supported media.
429	`daily_limit_reached`	The account used its daily transcription allowance.
503	`api_processing_unavailable / api_uploads_unavailable / queue_unavailable`	A required processing or upload backend is unavailable.
500	`internal_error`	The API encountered an unexpected failure.

Queued job failures

A create request can return 202 and the job can fail later while resolving or processing the source. In that case the GET request itself is successful, but the resource contains:

{
  "data": {
    "id": "95c3fdd8-…",
    "status": "failed",
    "error": "The source media could not be processed.",
    "text": null,
    "segments": null
  }
}

Map job failures before display

A queued job failure is processing output rather than a controlled immediate error envelope. Log it for diagnostics and translate it to an application-owned message before showing it to an end user.

Retry guidance

Fix 400, 401, 403, 413, and 415 requests before retrying.
Wait for the UTC allowance reset or change plan usage before retrying a daily-limit 429.
Use bounded exponential backoff for transient 503 and transport errors.
Do not repeatedly queue private, removed, or login-gated media.