Errors
Errors you might encounter when making requests to the Deepgram API
A record of errors and reasons you will receive them when using the Deepgram API.
Errors that could be returned on any endpoint.
400 Invalid JSON submittedWhen making a POST request with JSON data, you must include all required fields. If required filed are missing, or the submitted JSON is invalid, a 400 Bad Request will be returned. The response will be similar to the below, depending on the endpoint and how the JSON is malformed.
400 Unknown request body formatIf you receive the following error:
Often, this is caused by sending Deepgram a URL to transcribe, but failing to set a Content-Type: application/json header. When sending Deepgram a JSON payload containing a URL, the Content-Type: application/json must be set in the request.
If you are sending an audio file and not a URL, you may be sending corrupted audio. You can use tools such as ffprobe or Audacity to confirm that your audio file is valid.
401 Incorrect API keyProviding an invalid API key will return 401 Unauthorized with the following error.
401 Insufficient permissionsMaking a request that you do not have sufficient permissions for will return 401 Unauthorized with this error.
403 Insufficient permissionsMaking a request for a model that you do not have access to will return 403 Forbidden with this error.
404 UUID parsing failedProviding an invalid Project ID will fail parsing and return 404 Not Found and this response.
404 Project not foundWhen a project isn’t found it will result in 404 Not Found. It may be because;
402 Insufficient creditsWhen attempting to transcribe a file, you may not have sufficient funds to complete the request. This will result in a 402 Payment Required error with this error.
422 Unprocessable EntityWhen attempting to transcribe audio, Deepgram was unable to process the request because the audio data was incomplete or interrupted. This typically occurs when the connection is closed before the full audio payload is received, or when upload speed is too slow and the upload times out.
You can check client-side logs for evidence of interrupted uploads or timeouts. If the issue persists, contact support with the request ID and details about how the audio was uploaded. Including the original audio file, if possible, can help with troubleshooting.
429 Rate limit exceededWhen requests are made in excess of Deepgram’s rate limits, a 429 Too Many Requests is returned with the following error. An exponential-backoff retry strategy is recommended to accommodate rate-limiting when submitting a large volume of concurrent requests.
400 Unknown Model. Query parameters specify a model that does not exist.The model requested is not one of Deepgram’s voice models.
400 Failure to Parse Query ParametersThe query parameters were invalid. The message can be anything describing a failure to parse an invalid query string.
400 Input Text Contained No CharactersThe text payload contained no characters, resulting in Deepgram being unable to synthesize text into audio.
400 Unsupported Output Audio Format Requested in Query ParametersThe request provides a query string containing any combination of query parameters that describes an unsupported output audio format.
One or more of the following query parameters is unsupported:
encoding=[encoding]container=[container]sample_rate=[sample_rate]bit_rate=[bit_rate]message may be any one of:
container is not applicable when encoding=[encoding]”container=[container] is invalid when encoding=[encoding]”sample_rate is not applicable when encoding=[encoding]”sample_rate must be [list of valid sample rates] when encoding=[encoding]”bit_rate is not applicable when encoding=[encoding]”bit_rate must be [list of valid bit rates] when encoding=[encoding]”400 Failure to Parse Request Body as JSONThe request body did not deserialize as JSON successfully. The request body must specify exactly one of text or url in the body.
400 Failure to Parse Remote Text URL Provide in JSONThere was a failure to parse a remote text URL provided within the JSON body.
400 Failure to Fetch Remote Text from URLThere was a failure to retrieve remote text content from the specified URL.
message may be any of:
application/json with a text field or text/plain.”location header in its redirect response.”400 Invalid CallbackThe provided callback url was invalid.
413 Request Body Exceeded 2MBThe request body exceeded the 2MB limit, indicating that the payload size is too large to be processed.
413 Input Text Exceeded Character LimitThe text payload contained more than the maximum number of characters allowed.
400 Failure to Decode Request Body as UTF-8The payload cannot be decoded because it is not encoded as UTF-8.
415 Unsupported Content Type in RequestThe Content-Type header in the request is not supported, requiring it to be either text/plain or application/json.
422 Unprocessable ContentThe model failed to process the request.
429 Rate Limit ExceededWhen requests are made in excess of Deepgram’s rate limits.
503 Service UnavailableSome error codes, such as 400: Bad Request errors, can be prevented in your production code by careful testing and development. However, others, such as 503: Service Unavailable, can occur regardless of your implementation.
Below is a list of HTTP error codes that your production code should handle gracefully. Some of these errors may succeed if retried, while others (such as 414: URI Too Long) need to be handled by modifying the request.
The following errors are more likely to be encountered in a development environment. You may want to add error handling in your production code to gracefully handle these error codes as well.