Response Codes

We use standard HTTP codes to denote successful execution or indicate when errors occur. For some errors, the response will include additional information about the error, including an application error code and human readable error description.

Successful execution

Operations that execute successfully will return 2xx codes, and, where appropriate, will return the information requested directly in the response body. The table below shows the typical response codes, entities and headers used for the various HTTP verbs supported by the API:

Operation Verb HTTP Response code Notes Response body Response headers
GET 200   The requested data (order, document, etc) as JSON or XML  
POST 201 Used when the POST will result in a new entity (e.g., placing an order) Empty Location - will contain URL of new entity
POST 204 Used when the POST simply performs an operation, with no new entity created (e.g., canceling an order) Empty  

Error Handling

Operations that result in an error due to a problem on the client's part (eg invalid input) will standard 4xx codes. Operations that result in an error due to a problem in the Rev server will return 5xx codes.

Where a standard HTTP error is sufficiently descriptive (e.g., 401 (Not Authorized) or 404 (Not Found)), the response body will be empty. For other cases, we will use the generic response code for client error (400), and the response will include an error entity that gives further details about the error, including an application error code and a human readable error description. The format of this error entity is below: 

{
    /* Numeric error code. Each operation specifies possible error codes and their meanings. */
    "code": "10001",

    /* Human-readable error message */
    "message": "Invalid audio length"
}
    
<error>
    <!--
        Numeric error code. Each operation specifies possible error codes
        and their meanings.
    -->
    <code>10001</code>
    <!-- Human-readable error message -->
    <message>Invalid audio length</message>
</error>

The table below shows the HTTP response codes and entities used for some common error conditions:

Error Condition HTTP Response Code Response Body
The submitted data was invalid in some way 400 Error entity, in JSON or XML, with appropriate specific application error code and message, and possibly detail. Each API operation will document the possible application error codes
The user/client API keys were not specified, or were not valid 401 Empty
Requested operation is not valid (eg due to workflow rules or restrictions on the current user's role) 403 Empty
Requested item (eg order, document) does not exist 404 Empty
Too many requests / rate limiting 429 The rate at which Rev allows you to make requests. See the Retry-After header for how long to wait until making additional requests. We do not recommend polling for order status. Instead, use our notifications mechanism to get a callback of your order status
There was an unexpected error in the Rev code 500 Empty
The Rev API is down for maintenance 503 Some HTML that can be ignored