Error handling

When using the Async API, errors can occur at different stages of the workflow — from uploading files, to creating transcription requests, to webhook delivery. This guide explains how to detect, handle, and recover from errors in a robust way.

File upload errors

When uploading files:

• Ensure the file duration is ≤ 60 minutes (cannot be increased).
• Stay within your storage and file count quotas.
• If you exceed a limit, you’ll get an error.

How to recover:

• Delete old files to free up space.
• Request higher limits in the Soniox Console.

Transcription request errors

When creating transcriptions:

• Stay below 100 pending transcriptions at once.
• Keep your total (pending + completed + failed) under 2,000.
• If you exceed a limit, you’ll get an error.

How to recover:

• Wait for some pending jobs to complete.
• Delete completed/failed jobs to stay under the quota.
• Request higher limits in the Soniox Console.

Webhook delivery failures

Webhook delivery may fail if:

• Your server is unavailable.
• Your endpoint does not respond in time.
• An invalid response is returned.

Retry behavior

• Soniox automatically retries multiple times over a short period.
• If all attempts fail, the webhook is marked as permanently failed.

Recovery options

• Retrieve the transcription result manually using the transcription ID from the create transcription request.

Example:

curl https://api.soniox.com/v1/async/transcriptions/<transcription_id> \
  -H "Authorization: Bearer $SONIOX_API_KEY"