Errors

Overview

This page documents errors from the public REST API at api.soniox.com. It covers two channels:

1. REST API responses. Any 4xx or 5xx response from api.soniox.com carries a structured JSON error body with a stable error_type.
2. Async transcription failures. A POST /v1/transcriptions call returns 200, but the transcription job ends in status: failed. The reason is stored on the job and returned by GET /v1/transcriptions/{id} in the error_type and error_message fields. The HTTP call succeeded; the transcription itself did not.

For both channels, error_type is the stable identifier you should branch on in code. The human-readable message may change over time; error_type will not. Every error_type is documented as a section on this page so the more_info URL on the response lands at the right anchor.

The realtime WebSocket APIs and the TTS REST API are separate APIs with their own error formats. See Other APIs below.

REST API error response

REST API errors return a JSON body conforming to the ApiError schema:

{
  "status_code": 401,
  "error_type": "unauthenticated",
  "message": "Incorrect API key provided. You can get an API key at https://console.soniox.com",
  "validation_errors": [],
  "request_id": "3d37a3bd-5078-47ee-a369-b204e3bbedda",
  "more_info": "https://soniox.com/docs/api-reference/errors#unauthenticated"
}

Async transcription failures

When you create a transcription with POST /v1/transcriptions, the call returns 200 and a transcription object as soon as the job is accepted. The work itself happens asynchronously: the audio is downloaded (if a URL was supplied), then transcribed.

If the job fails, the HTTP layer doesn't see the failure. Instead, GET /v1/transcriptions/{id} returns status: "failed" with error_type and error_message fields populated. Always check status and read these fields when polling a transcription.

{
  "id": "84c32fc6-4fb5-4e7a-b656-b5ec70493753",
  "status": "failed",
  "error_type": "file_download_failed",
  "error_message": "Failed to download audio from the provided URL.",
  "...": "..."
}

The following error_type values can appear on a failed transcription row:

• internal_error
• organization_balance_exhausted
• organization_monthly_budget_exhausted
• project_monthly_budget_exhausted
• invalid_audio_file
• file_download_blocked
• file_download_failed
• transcription_output_too_long
• model_not_available

Failed async jobs are not auto-retried. Fix the cause and submit a new transcription.

API error types

Each section below documents one error_type.

internal_error

HTTP 500 on REST, also on failed async transcriptions

Cause. Unhandled server-side exception, or an unrecoverable internal inconsistency.

Solution. Retry once. If the error persists, contact support@soniox.com and include the request_id from the response.

unauthenticated

HTTP 401 on REST

Cause. The request did not authenticate. The Authorization header was missing, or the API key was malformed, revoked, expired, scoped to a different environment, or longer than 256 characters. Temporary API keys can also fail here when they are expired, single-use and already consumed, or used for an action they were not issued for.

Solution. Pass a valid key as Authorization: Bearer <SONIOX_API_KEY>. Get or rotate API keys in the Soniox Console. For client apps, use a temporary API key.

invalid_request

HTTP 400 on REST

Cause. The request body or query parameters failed validation. Common triggers: a required field is missing, a value is out of range, an enum value is unknown, a multipart upload is malformed or has unknown size, an uploaded file exceeds the per-file byte limit, or a request-level invariant is violated (for example, end_time not strictly after start_time on GET /v1/usage-logs).

When the cause is a per-field validation failure, the response includes validation_errors with the exact location and reason for each field:

{
  "status_code": 400,
  "error_type": "invalid_request",
  "message": "Invalid request.",
  "validation_errors": [
    {
      "error_type": "missing",
      "location": "file.file",
      "message": "Field required"
    }
  ],
  "request_id": "..."
}

Solution. Read validation_errors (or message for ad-hoc validation failures) and resend the request with corrected values.

invalid_cursor

HTTP 400 on REST

Cause. The cursor query parameter on a paginated endpoint (/v1/files, /v1/transcriptions, /v1/usage-logs) could not be decoded. The cursor is opaque and only valid when copied verbatim from the previous page's next_page_cursor; any modification, truncation, or stale cursor triggers this error.

Solution. Omit cursor to start from the first page, or pass the exact next_page_cursor from the previous response without modification. Keep all other query parameters constant across pages of the same listing.

limit_exceeded

HTTP 429 on REST

A single error_type covers many distinct limits. Read message to find out which one was hit. The sub-causes below are grouped by what kind of limit triggered the response.

All current limits and your usage are visible in the Soniox Console. Per-product reference: Async STT, Real-time STT, REST TTS, Real-time TTS.

Requests per minute (RPM)

Too many calls of the same kind in a 60-second window, evaluated per organization or per project. RPM limits exist for:

• WebSocket transcription
• Async transcription
• File management
• Text-to-Speech
• Temporary API key creation
• Usage logs

Solution. Slow down, batch where possible, or raise the limit in the console: organization limits or project limits.

Concurrent requests

Too many simultaneous in-flight requests on the organization or project (applies to streaming workloads such as the realtime Speech-to-Text and Text-to-Speech).

Solution. Reduce parallelism in the client, or request a higher concurrent-requests cap in the console.

Total file count / total file size (GB)

Adding this file would put the organization or project over its retained-storage cap (files_total_count or files_total_size_gb).

Solution. Delete unused files via DELETE /v1/files/{id}, or raise the cap in the console.

Pending file count

Too many uploaded files are awaiting transcription (transcribe_async_pending_num_files).

Solution. Wait for in-flight transcriptions to complete, then retry.

Total transcription count / pending transcription count

Analogous caps on the number of stored transcriptions (transcribe_async_total_num_files, transcribe_async_pending_num_files).

Solution. Delete completed transcriptions with DELETE /v1/transcriptions/{id}, or raise the cap.

organization_balance_exhausted

HTTP 402 on REST, also on failed async transcriptions

Cause. The available balance has dropped to zero. Raised before the request runs, and also evaluated when an async job is about to start downloading or transcribing. In the async case the job moves to failed with this error_type.

Solution. Top up at Billing overview or enable autopay. Failed async jobs are not auto-retried; resubmit after funding.

organization_monthly_budget_exhausted

HTTP 402 on REST, also on failed async transcriptions

Cause. The organization has hit its configured monthly budget cap (monthly_budget_usd). Resets at the start of the next calendar month.

Solution. Raise the cap on the organization limits page, or wait for the month to roll over.

project_monthly_budget_exhausted

HTTP 402 on REST, also on failed async transcriptions

Cause. The project has hit its configured monthly budget cap.

Solution. Raise the cap on the project limits page, or wait for the month to roll over.

invalid_audio_file

HTTP 400 on POST /v1/files upload, also on failed async transcriptions

Cause. The audio could not be decoded, contains no audio stream, or exceeds the model's maximum audio duration. For async jobs this is set during the download / convert step or during the transcribe step's duration recheck.

Solution. Try transcribing the file directly in the Soniox Console to confirm whether the file itself is the problem. If it is, re-encode to a supported container/codec or split long audio into shorter segments. See the supported audio formats.

file_download_blocked

Failed async transcriptions only, no HTTP error

Cause. The supplied audio_url could not be fetched for safety reasons: the URL resolved to a private or otherwise blocked IP (SSRF guard).

Solution. Use a publicly reachable URL whose host resolves to a routable IP. If the project or organization was deleted, recreate it (or use a different one) and resubmit.

file_download_failed

Failed async transcriptions only, no HTTP error

Cause. Fetching audio_url failed: HTTP error (4xx / 5xx), DNS failure, TLS failure, connection timeout, or the server closed the connection mid-stream. 4xx responses are not retried; other transient failures are retried internally up to a bound before the job is marked as failed.

Solution. Make the URL reachable and stable. For files you control, prefer uploading via POST /v1/files rather than relying on a remote URL.

transcription_output_too_long

Failed async transcriptions only, no HTTP error

Cause. The transcription completed but produced more output than the model is allowed to return in a single job. Not expected to occur in normal use. If you see this error_type, please contact support@soniox.com with the transcription ID.

model_not_available

HTTP 400 on REST, also on failed async transcriptions

Cause. The requested model is unknown, has been retired, or is not enabled for the calling project or region.

Solution. Use an async model from the STT models catalog. If you've been pinning a specific model, switch to a current one before its retirement date.

file_not_found

HTTP 404 on REST

Cause. No file with the given ID exists in the project the API key belongs to. Returned for IDs that never existed, IDs that were deleted, and IDs that exist but belong to a different project. Soniox does not leak cross-project existence.

Solution. Confirm the ID by listing files via GET /v1/files, and make sure the API key is scoped to the project that owns the file.

transcription_not_found

HTTP 404 on REST

Cause. No transcription with the given ID exists in the caller's project. Same semantics as file_not_found: deleted, never existed, or belongs to a different project.

Solution. Confirm the ID with GET /v1/transcriptions, and check that the API key is scoped to the project that owns the transcription.

transcription_invalid_state

HTTP 409 on REST

The transcription exists but is in a state that doesn't allow the requested operation. Read message for the specific reason.

Not completed yet

GET /v1/transcriptions/{id}/transcript while status is queued, downloading, or transcribing.

Solution. Poll GET /v1/transcriptions/{id} until status is completed, or configure a webhook on the transcription to be notified.

Failed

The transcript was requested for a transcription that ended in status: "failed".

Solution. Read error_type and error_message from GET /v1/transcriptions/{id} to see why, and submit a new transcription after fixing the cause.

No longer available

Transcript data was retained for a limited window after completion and has since been purged.

Solution. Re-submit the original audio as a new transcription.

Cannot delete while processing

DELETE /v1/transcriptions/{id} while status is transcribing.

Solution. Wait for status to reach completed or failed, then retry the delete.

Other APIs

The realtime WebSocket APIs and the TTS REST API are separate APIs with their own error formats. They are documented on the API's own reference page:

• TTS REST API (tts-rt.soniox.com/tts): JSON error_code / error_message before streaming starts, HTTP trailers (X-Tts-Error-Code, X-Tts-Error-Message) for mid-stream errors. See Error handling on the TTS REST API page.
• STT WebSocket API: see the per-endpoint error table on STT WebSocket API.
• TTS WebSocket API: see the per-endpoint error table on TTS WebSocket API.

Getting help

If you can't determine the cause from error_type and message, or if an internal_error keeps recurring, contact support@soniox.com and include:

• The request_id from the error response.
• The error_type and message.
• The endpoint and HTTP method, or for async failures the transcription ID.
• A short description of what you were trying to do.