Difference between revisions of "Errors"
(Created page with '== 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 info…') |
(No difference)
|
Latest revision as of 14:46, 18 April 2014
Contents
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.
