Error handling
Learn about async API 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.
General errors
If a request fails, the API will return a JSON error response with more information. Always log or print the response for debugging.
The full list of Error codes provides details on all possible errors and how to resolve them.
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: