Errors

Errors

When there is an error processing a request, the API will return an HTTP error response code denoting the type of error. The system will also return additional information in the body of the response. Errors can be formatted in JSON or XML, depending on the Accept header of the request.

This page documents the behavior of synchronous errors returned by the API.

Fault Element	Error Codes	Custom Fields
appsFault	500, 400, 409 and other codes
itemNotFound	404	resourceType - What resource in the request that was not found (Domain, Mailbox, etc.)
unauthorized	403
badRequest	400

Scenarios

Here are scenarios that demonstrate the various errors that the API might return. Each scenario includes a request and response. The request shows the HTTP verb and URL, and the response shows the response code, followed by the response body.

400 Bad Request

The following HTTP request and response demonstrates an HTTP 400 / badRequestFault.

The response is an error because the request does not include a required field.

request:
POST https://api.emailsrvr.com/v1/customers/me/domains/example.com/rs/mailboxes/user.1

Response:
400 Bad Request
{
    "badRequestFault": {
        "message": "Missing required field: password",
        "details": "4/11/2014 3:03:24 PM",
        "code": 400,
    }
}

403 Unauthorized

The following HTTP request and response demonstrates an HTTP 403 / unauthorizedFault.

The response is an error because the request does not include valid authentication information.

Request:
GET https://api.emailsrvr.com/v1/customers/me/domains/example.com/rs/mailboxes/user.1

Response:
403 Unauthorized
{
    "unauthorizedFault": {
        "message": "Authentication failed.",
        "details": "4/11/2014 3:06:57 PM",
        "code": 403
}

Throttling

The same request as before might also return an error if the user has made too many requests and is throttled. The request and response would look like this:

403 Unauthorized
{
    "unauthorizedFault": {
        "message": "Exceeded request limits",
        "details": "4/11/2014 3:09:30 PM",
        "code": 403
    }
}

404 Not Found

The following HTTP request and response demonstrates an HTTP 404 / itemNotFoundFault.

This response is an error because the domain specified in the request does not exist.

Request:
GET https://api.emailsrvr.com/v1/domains/idontexist.com/rs/mailboxes/

Response:
404 Not Found
{
    "itemNotFoundFault": {
        "resourceType": "Domain",
        "message": "idontexist.com not found",
        "details": "4/11/2014 2:59:51 PM",
        "code": 404
    }
}

409 Conflict

The following HTTP request and response demonstrates an HTTP 409 / appsFault

This response in an error because the Distribution List is currently updating.

request:
PUT https://api.emailsrvr.com/v1/customers/me/domains/example.com/ex/distributionLists/list.1
{
  "DisplayName": "Distribution List!"
}

response:
409 Conflict
{
    "appsFault": {
        "message": "Distribution List is currently Updating please try again soon",
        "details": "4/14/2014 4:39:17 PM",
        "code": 409,
    }
}

500 Internal Server Error

The following HTTP request and response demonstrates an HTTP 500 / appsFault.

This response is an error because of an internal server error

Request:
GET https://api.emailsrvr.com/v1/domains/idontexist.com/rs/mailboxes/

Response:
404 Not Found
{
    "appsFault": {
        "message": "Internal Server Error",
        "details": ""4/11/2014 3:19:57 PM",
        "code": 500
    }
}

XML

<?xml version="1.0" encoding="utf-8"?>
<itemNotFoundFault 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" code="404" 
    xmlns="http://api.emailsrvr.com/v0/Schemas">
    <message>exchange2013.davsdfsdf not found</message>
    <details>4/14/2014 4:09:08 PM</details>
    <resourceType>Domain</resourceType>
</itemNotFoundFault>

The error code is returned in the body of the response for convenience. The message section returns a human-readable message that is appropriate for display to the end user. The details section is optional and may contain information—for example, a stack trace—to assist in tracking down an error. The detail section may or may not be appropriate for display to an end user. The root element of the fault (e.g. appsFault) may change depending on the type of error. The following is a list of possible common root elements along with their associated error codes. More specific faults may be may exist for different resources and will be documented with those resources.

From an XML schema perspective, all API faults are extensions of the base fault type AppsAPIFault. When working with a system that binds XML to actual classes (such as JAXB), one should be capable of using AppsAPIFault as a “catch-all” if there's no interest in distinguishing between individual fault types.

Legacy Header

Prior to faults in the body of HTTP responses, the only information returned to users was the HTTP status code and an HTTP header x-error-message with the error message. This functionality has been kept for backwards compatibility but retrieving fault information in the HTTP body is the recommended approach for new applications.