General 4xx customer issues

Introduction

When a customer reaches out with a 4xx error, it means that something is wrong with their API request. This playbook will touch on how to troubleshoot common 4xx errors. It is also worth noting that when a transcription completes with an error, we will return an error key in the JSON response for the GET request. We should educate customers on the error key in case they are not aware of it (see here for our error handling cookbook).

Procedures

Finding the Error Message in Datadog

If a customer is asking why their transcription failed, ask for the transcription id.

Open Datadog and navigate to “Logs” on the sidebar.
Enter @transcript_id:<transcript-id> in the search bar.
Once the logs have finished loading, you can ctrl/cmd + F “Client failed transcript” to find the specific error message that was received.

Common 4xx Messages

Download Error: Forbidden URL

A forbidden URL error occurs when AssemblyAI cannot access the provided URL. A common reason for this error is that the permissions settings of an S3 bucket for the provided URL are blocking us from accessing the audio file.

To resolve this issue, the developer can use pre-signed URLs to allow AssemblyAI temporary access to the files for processing.

Download Error: 404 Client Error: Not Found for url

This error occurs when a URL used in the audio_url is not found. To resolve this, ask the customer to check for any typos and make sure that the link does not point to a webpage that does not exist, has been moved, or has a dead or broken link.

File does not contain audio, appears to be text/html

The URL must point to a downloadable file. Customers can use an S3 bucket, cloud storage or our upload endpoint to generate a valid URL.

If you use a Youtube video as the URL in the audio_url parameter, you will get the above error since Youtube links do point to a downloadable video. You may get customers asking if we accept specific links like Youtube, Github etc. Here are some solutions when customers inquire about these types of links:

How to Get YouTube Video Transcripts with yt-dlp

How to Get Transcripts Using Google Drive Links

Transcribing Files Hosted on GitHub with AssemblyAI

Transcribing from an S3 Bucket