If you are having trouble using any of our APIs we want to know and help you debug the problem.


During the lifecycle of an API we will release incremental improvements.

Under certain circumstances we may increment the version of the API:

  • backward compatibility could not be preserved in order to support a new feature or bugfix
  • significant changes to sound quality produced

You do not need to specify which version of an API you wish to use and will use the latest by default. You can check out the Release Notes to learn about recent changes.


The api_version is returned when you GET /media/enhance or GET /media/analyze along with progress and status.

    "api_version": "v1.0",
    "path": "/media/enhance",
    "progress": 100,
    "result": { },
    "status": "Success"

If you observe a change in behavior, please review the Release Notes and note the date of a release which may not be reflected in the version number but may have underlying algorithm changes to media processing behavior.


The version you want to use in a POST /media/enhance or POST /media/analyze request can be specified by including an x-api-version header. For example:

curl -X POST \
     --header "x-api-key: $DOLBYIO_API_KEY" \
     --header "x-api-version: v1.0" \
     --data '{
         "input": "dlb://in/example.mp3",
         "output": "dlb://out/example-metadata.json"


This section identifies some of the common errors you may see when debugging and how to troubleshoot them.


This is an authentication error. Make sure you are providing a valid API key as the x-api-key header in your request.


This is a read error on the URL provided as input. If you are using a pre-signed URL or protected server it may be that the tokens or keys are invalid for accessing the file.


This is a processing error if we are able to read the file but it is not supported or corrupted in some way.

Potential Causes:

  • Audio must be a minimum of 1 second in order to receive output
  • Check the Supported Formats to make sure it is the type of media we support
  • Try a different media file, we have a few samples that are known to work, for example, airplane.original.mp4


This is a read or write error if the input or output parameters given as an AWS S3 location reference an invalid bucket.


This is a write error if the URL provided as output is inaccessible. The endpoint must accept a PUT request along with a concluding HEAD or GET request that validates the full file has been stored.


This is a general access error to read or write a given input and output parameters.


This problem can occur if we are unable to read or write media in a reasonably expected amount of time. If this problem occurs frequently please raise a support ticket so that we can work with you on a solution:


This problem can occur if you exceed usage thresholds for the Media Processing APIs. If you are making an unexpectedly high volume of API calls this problem could be triggered. If you believe this is an error please raise a support ticket at


If you are on a free-tier this may indicate you have consumed your free processing minutes. Check that your billing details on file are correct. If you anticipate an error, please use the Contact form and raise a question.


If you receive an InternalError when processing media it indicates that we were unable to successfully identify and fix the issue automatically. There are a number of reasons this can occur depending on your media workflows.

Steps you can take:

  1. Confirm that the type of media you want to process is in the table of our Supported Formats
  2. Raise a support ticket by visiting and if possible share an example of your media. We'll work with you to determine the issue with the media and find a solution.