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