Errors Explanation

Error Response Types

The Verbit API has two distinct types of error responses depending on when and where the error occurs:

1. Immediate Request Errors

These errors occur during the API request validation and return immediately with this format:

JSON

{
  "ErrorType": "ERROR_TYPE_STRING",
  "ErrorComment": "Error explanation"
}

Common ErrorType values:

• BAD_API_TOKEN - Invalid API token
• MISSING_PARAMETER - Required parameter omitted
• INVALID_OPTION - Parameter value incorrect/unsupported
• INVALID_QUERY - Invalid parameter combination
• INVALID_URL - URL invalid or inaccessible
• ITEM_NOT_FOUND - Requested item not found

UUID Errors

If you encounter "UUID already exists" errors:

• This typically occurs on the /job/new endpoint.
• Indicates a race condition in UUID generation.
• Action: Retry the request with the same parameters.

2. Processing Errors

These errors occur during job processing and are returned in the /job/info endpoint response when job status is "Failure". They appear in the errors array with this format:

JSON

{
  "errors": [
    {
      "code": "error_code",
      "message": "Error message"
    }
  ]
}

Common Processing Errors

Media Processing Errors

Code	Message	Explanation	Causes	Troubleshooting
failed_transcoding	"Transcoding error"	Occurs when the system fails to convert the media file into a processable format.	Usually indicates corrupted media file or unsupported format.	- Verify file integrity by playing it in a media player - Use ffmpeg to check file format and structure - Try converting to a different format before uploading - Re-export the file from the original source if possible
failed_transcribing	"Transcribing error"	Occurs when the system fails to process the audio content.	Usually indicates issues with the sound quality or content	- Listen to the audio file to verify it's audible and clear - Check for issues like: - Excessive background noise - Very low volume - Distorted audio - Corrupted audio segments - Very unclear speech - If the audio is clearly audible but still fails, contact support for investigation

Media Quality Errors

Code	Message	Action
bad_audio_quality	"Audio is hard to recognize"	Check audio quality, consider re-recording with better equipment or conditions.
no_speech	"No speech detected"	Verify the media file contains spoken content.

Upload and Access Errors

Code	Message	Action
media_upload_error	"Media file is unreachable"	Verify the media URL is accessible and not expired.
no_speech	"No speech detected"	Verify the media file contains spoken content.
INVALID_QUERY	- "file already uploaded" - Refers to notes/attachments with the same name/URL. - "media already uploaded" - Refers to the main media file already being added.	For retries, these errors can be safely ignored as the content is already present.

Limit and Constraint Errors

Code	Message	Action
exceeded_allowed_duration	"File exceeded maximum length of %{hours} hours"	Split long recordings into smaller segments. Note: there is no specific file duration limit, it's very rare, but different combination of service may cause that issue.
audio_minutes_limit, audio_minutes_limit_on_account	- "Max profile limit of audio minutes reached" - "Max account limit of audio minutes reached"	Contact support to increase limits or upgrade account.

Language and Processing Errors

Code	Message	Action
foreign_language	"Unsupported language"	Verify media language and make sure that corresponding language/profile is selected.

Best Practices

1. Error Handling

   • Always check both error response types.
   • Implement appropriate retry logic for transient errors.
   • Log error details for troubleshooting.

2. File Upload

   • Ensure media files are in supported formats.
   • Verify URLs are accessible for at least 24 hours.
   • Check media language.

3. Monitoring

   • Regularly poll /job/info for job status.
   • Implement webhook notifications for real-time updates.
   • Monitor error patterns for systematic issues.
   • Check https://verbit.statuspal.io/ for known issues.

Getting Help

If you encounter persistent errors or need clarification:

1. Check this documentation for known solutions.
2. Review your API implementation.
3. Contact Verbit support with specific error details and job IDs.