Error handling
Passport APIs will use standard HTTP status codes to reflect the appropriate result of the request. The set of codes we leverage are outlined below. In addition to setting the appropriate HTTP status code, when a problem occurs the API may respond with additional detail in the response body. The format of this detail will follow the standard defined by RFC 7807 which outlines a standard model for describing “Problem Details for HTTP APIs.” Passport defines it’s use of RFC 7807 with the following specifics:
- Problem detail “Types” are a URN that provide a descriptive, human readable error code that is prefixed with the namespace: “io.passportlabs:error:”
- Problem types that are specific to each API will be documented as part of that API
- If additional detail is included as part of the problem detail, those custom fields will be wrapped in an element that is titled “additional_details”
An example is provided below:
{
"type": “io.passportlabs:error:zone_not_found",
"title": "Zone not found ",
"detail": "The zone named 501 was not found",
“additional_details”: {
"zone_id": 501
}
}
HTTP Status Codes
The following HTTP status codes may be leveraged by Passport APIs to convey the appropriate result of a request. Not all APIs will support all of the codes listed below. What codes may occur will be included in the documentation for each API.
Success Responses (2xx)
Code | Standard Usage |
---|---|
200 | Success. Standard success response that should contain a response body |
201 | Created. When an entity was successfully created/added |
202 | Accepted. When the request was accepted but will be processed asynchronously |
204 | No Content. When the request was successful and there is no response body |
207 | Multi-status. When there are multiple status codes for different parts of a bulk request |
Client Errors (4xx)
Code | Standard Usage |
---|---|
400 | Bad Request. When the input data fails validation. Can also be used when no other 400 error applies |
401 | Unauthorized. In general, this is used when sufficient trust has not been established in the identity of the client |
403 | Forbidden. In general, this is used when there is insufficient authority to complete a task |
404 | Not Found. When a resource is requested and does not exist |
406 | Not Acceptable. When the requested media type is not supported |
410 | Gone. May be used when the API wishes to convey that the requested resource was previously deleted |
413 | Large Payload. When the request contains a payload that is larger that the API is willing or able to process |
415 | Unsupported. When the provided content type is not able to be processed |
429 | Too Many Requests. When the client has exceeded their specified rate limit |
Server Errors (5xx)
Code | Standard Usage |
---|---|
500 | Server Error. When the request was valid but the API was unable to process it appropriately |
502 | Bad Gateway. When the API has a dependency that is unavailable or fails to process successfully |
503 | Unavailable. When the resource is temporarily unavailable. A retry may be successful |
504 | Timeout. When the API has a dependency that has timed out, resulting in the API failing to process to completion |