Parsing API Responses

Browse by products and services

The (mt) Media Temple API uses HTTP status codes to indicate the result of API calls to the client. In addition to this, the (mt) Media Temple API also provides additional information in the response body to identify specific faults and other data to the client.

HTTP Response Codes

The following is a list of response codes that may be returned from the API server with a description for each. This list is not exhaustive, but includes the typical responses that will be returned. Depending on the behavior of the client and interim proxies, other response codes may be generated and should be considered general failures.

Status Code Description
200 Successful, check response body.
201 Successfully created.
202 Request accepted but not yet processed.
400 There was an error in the request input.
401 Not Authorized. The authenticated user does not have permission to perform the operation.
403 Permission Denied. The specified credentials are invalid.
404 The specified resource was not found.
409 There was a conflict with an existing object or process.
500 Internal Server Error
503 Service Unavailable

Response Body

Every successful GET request (200 response) is intended to have an entity response body (e.g. { someEntity : { "key": "value" } }). Every other response body should contain a response in the following format.

  "response" : {
    "statusCode" : 403,
    "timeStamp" : 1284432567701,
    "date" : "2010-09-14T02:49:27.701+0000",
    "errors" : [ {
      "errorCode" : "AuthError",
      "message" : "Unable to authenticate user"
    } ],
    "custom" : [ ]

The statusCode property should contain the same code as the HTTP status code and every response parser should ensure they match. This is especially important for status codes such as 404 Not Found. When looking up a resource (e.g. GET /resource/1), a 404 response code will be returned to indicate that the existing resource does not exist. However, should an intermediate proxy or web server have problems and return an HTTP status code of 404, the client might inappropriately conclude that the resource does not exists.

The response always includes both the timeStamp in milliseconds since epoch and date in W3C Datetime Format - Complete date plus hours, minutes, seconds and a decimal fraction of a second.

The errors property in the response may contain one or more errors that occurred. Every resource URL may return both common error responses and unique responses. Please see the appropriate resource API documentation for unique error codes.

The custom property in the response may contain one or more custom return values, which will be documented in the API documentation for each resource API.