Errors

A record of errors and reasons you will receive them when using the Deepgram API.

General API errors

Errors that could be returned on any endpoint.

400 Invalid JSON submitted

When 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.

{
  "category": "INVALID_JSON",
  "message": "Invalid JSON submitted.",
  "details": "Json deserialize error: missing field `xxx` at line 7 column 1",
  "request_id": "uuid"
}
---
{
  "err_code": "Bad Request",
  "err_msg": "Content-type was application/json, but we could not process the JSON payload.",
  "request_id": "uuid"
}
---
{
  "category": "INVALID_JSON",
  "message": "Invalid JSON submitted.",
  "details": "Json deserialize error: expected `:` at line 3 column 13",
  "request_id": "uuid"
}

400 Unknown request body format

If you receive the following error:

{
  "err_code": "Bad Request",
  "err_msg": "Bad Request: failed to process audio: corrupt or unsupported data",
  "request_id": "uuid"
}

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 key

Providing an invalid API key will return 401 Unauthorized with the following error.

{
  "err_code": "INVALID_AUTH",
  "err_msg": "Invalid credentials.",
  "request_id": "uuid"
}

401 Insufficient permissions

Making a request that you do not have sufficient permissions for will return 401 Unauthorized with this error.

{
 "err_code":"INSUFFICIENT_PERMISSIONS",
 "err_msg":"User does not have sufficient permissions.",
 "request_id":"uuid"
}

403 Insufficient permissions

Making a request for a model that you do not have access to will return 403 Forbidden with this error.

{
 "err_code":"INSUFFICIENT_PERMISSIONS",
 "err_msg":"Project does not have access to the requested model.",
 "request_id":"uuid"
}

404 UUID parsing failed

Providing an invalid Project ID will fail parsing and return 404 Not Found and this response.

UUID parsing failed: invalid character: expected an optional prefix of `urn:uuid:` followed by [0-9a-zA-Z], found `p` at 1

404 Project not found

When a project isn't found it will result in 404 Not Found. It may be because;

• the Project ID is incorrect
• the Project ID is for a project that has been deleted
• the Project ID is not associated with the API key used to make the request

{
  "err_code": "PROJECT_NOT_FOUND",
  "err_msg": "Project not found."
}

Speech to Text errors

Errors specific to making transcription requests.

402 Insufficient credits

When 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.

{
  "err_code": "ASR_PAYMENT_REQUIRED",
  "err_msg": "Project does not have enough credits for an ASR request and does not have an overage agreement.",
  "request_id": "uuid"
}

429 Rate limit exceeded

When 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.

{
  "err_code": "TOO_MANY_REQUESTS",
  "err_msg": "Too many requests. Please try again later",
  "request_id": "uuid"
}

Text to Speech Errors

400Unknown Model

The model requested is not one of Deepgram's voice models.

{
  "err_code": "Bad Request",
  "err_msg": "Bad Request: No such model/version combination found.",
  "request_id": "[unique_request_id]"
}

400 Failure to Parse Query Parameters

The query parameters were invalid. The message can be anything describing a failure to parse an invalid query string.

{
  "err_code": "INVALID_QUERY_PARAMETER",
  "err_msg": "Failed to deserialize query parameters: [message]",
  "request_id": "[unique_request_id]"
}

413 Request Body Exceeded 2MB

The request body exceeded the 2MB limit, indicating that the payload size is too large to be processed.

{
  "err_code": "PAYLOAD_TOO_LARGE",
  "err_msg": "Payload size exceeds limit of 2 MB.",
  "request_id": "[unique_request_id]"
}

400 Input Text Contained No Characters

The text payload contained no characters, resulting in Deepgram being unable to synthesize text into audio.

{
  "err_code": "Bad Request",
  "err_msg": "Input text contains no characters.",
  "request_id": "[unique_request_id]"
}

413 Input Text Exceeded Character Limit

The text payload contained more than 2000 characters, which is above the character limit for text-to-speech request.

{
  "err_code": "Payload Too Large",
  "err_msg": "Input text exceeds maximum character limit of 2000.",
  "request_id": "[unique_request_id]"
}

400 Unsupported Output Audio Format Requested in Query Parameters

The request provides a query string containing any combination of query parameters that describes an unsupported output audio format.

{
  "err_code": "INVALID_QUERY_PARAMETER",
  "err_msg": "Unsupported audio format: [message]",
  "request_id": "[unique_request_id]"
}

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]"

415 Unsupported Content Type in Request

The Content-Type header in the request is not supported, requiring it to be either text/plain or application/json.

{
  "err_code": "UNSUPPORTED_MEDIA_TYPE",
  "err_msg": "`Content-Type` header is not supported. `Content-Type` must be either `text/plain` or `application/json`.",
  "request_id": "[unique_request_id]"
}

400 Failure to Decode Request Body as UTF-8

The payload cannot be decoded because it is not encoded as UTF-8.

{
  "err_code": "PAYLOAD_ERROR",
  "err_msg": "Failed to decode payload as UTF-8.",
  "request_id": "[unique_request_id]"
}

400 Failure to Parse Request Body as JSON

The request body did not deserialize as JSON successfully. The request body must specify exactly one of text or url in the body.

{
  "err_code": "PAYLOAD_ERROR",
  "err_msg": "Failed to deserialize JSON payload. Please specify exactly one of `text` or `url` in the JSON body.",
  "request_id": "[unique_request_id]"
}

400 Failure to Parse Remote Text URL Provide in JSON

There was a failure to parse a remote text URL provided within the JSON body.

{
  "err_code": "PAYLOAD_ERROR",
  "err_msg": "Failed to parse URL in JSON body.",
  "request_id": "[unique_request_id]"
}

400 Failure to Fetch Remote Text from URL

There was a failure to retrieve remote text content from the specified URL.

{
  "err_code": "REMOTE_CONTENT_ERROR",
  "err_msg": "[message]",
  "request_id": "[unique_request_id]"
}

message may be any of:

• "Failed to deserialize remote text data. Please provide application/json with a text field or text/plain."
• "URL for media download must be publicly routable."
• "Could not determine if URL for media download is publicly routable."
• "Could not parse URL as a URI."
• "The remote server hosting the media failed to include a location header in its redirect response."
• "Could not parse remote media server's redirect location as a valid UTF-8 string."
• "Could not parse remote media server's redirect location as a URL."
• "The remote server hosting the media returned a client error: [HTTP status]."
• "The remote server hosting the media failed to return valid data."
• "The remote server hosting the media returned too many redirects."

400 Invalid Callback

The provided callback url was invalid.

{
  "err_code": "INVALID_QUERY_PARAMETER",
  "err_msg": "Invalid callback url.",
  "request_id": "[unique_request_id]"
}

429 Rate Limit Exceeded

Status 429

When requests are made in excess of Deepgram's rate limits.

{
  "err_code": "Too Many Requests",
  "err_msg": "Please try again later.",
  "request_id": "[unique_request_id]"
}

Handling HTTP Errors

Production

Some 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.

• 408 Request Timeout: The server timed out waiting for the request.
• 411 Length Required: The server refuses to accept the request without a defined Content-Length.
• 413 Request Entity Too Large: The request is larger than the server is willing or able to process.
• 414 URI Too Long: The server is refusing to service the request because the request-target is longer than the server is willing to interpret.
• 429 Too Many Requests: The user has sent too many requests in a given amount of time.
• 499 Client Closed Request: A non-standard status code indicating that the client closed the connection.
• 500 Internal Server Error: A generic error message indicating that the server has encountered a situation it doesn't know how to handle.
• 502 Bad Gateway: The server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request.
• 503 Service Unavailable: The server is not ready to handle the request. Common causes include a server that is down for maintenance or is overloaded.
• 504 Gateway Timeout: The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server or some other auxiliary server it needed to access in order to complete the request.

Development

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.

• 400 Bad Request: The server could not understand the request due to invalid syntax.
• 401 Insufficient permissions: The project does not have permissions to access the requested features or model.
• 401 Unauthorized: The API key is invalid or unauthorized.
• 402 Payment Required: The project has insufficient funds to complete the request.
• 403 Forbidden: The server understood the request but refuses to authorize it.
• 404 Not Found: The specified entity ID could not be found.