Search…
Error Handling
This document describes how REST APIs should present errors to clients consuming their services.
When an error occurs in a API, the service should return the error to the calling client in an informative and structured manner. The API should return information about the error in the response body.

Response Body

When an error occurs, a REST API should respond with an 4xx or 5xx HTTP status code and the response should contain a Problem Details object as described in the IETF RFC7807 documentation.

Problem Details Object

For REST APIs the Problem Details object is modelled as a JSON object. The format is identified with the "application/problem+json" content-type.
The type string is the primary problem identifier and is, as such, required. Every other field is optional but it is HIGHLY RECOMMENDED to at least have title and status strings present in the error response.
  • type (string) A URI reference that identifies the
    problem type. This specification encourages that, when
    dereferenced, it provides human-readable documentation for the
    problem type.
  • title (string) (Optional) A short human-readable summary of the problem type. It
    SHOULD NOT change from occurrence to occurrence.
  • status (number) (Optional) The HTTP Status Code generated by the origin server for
    this occurrence of the problem.
  • detail (string) (Optional) A human-readable explanation of the problem. This MAY
    differ from occurrence to occurrence.
  • instance (string) (Optional) A URI reference that identifies the specific
    occurrence of the problem.
  • extensions (Optional) Any Problem Detail object can contain custom
    extensions specific to the REST API.
    • traceId (string) A very common custom extension used to further clarify
      the context in which the error occurred.
    • params (Array) A common custom extension used to indicate which
      parameters were being used when the error occurred.

REST Error Response Examples

Simple Response
1
{
2
"type": "https://example.com/probs/out-of-credit",
3
"title": "You do not have enough credit.",
4
"status": 403,
5
"detail": "Your current balance is 30, but that costs 50.",
6
"instance": "/account/12345/msgs/abc"
7
}
Copied!
Response With Extensions
1
{
2
"type": "https://example.com/probs/out-of-credit",
3
"title": "You do not have enough credit.",
4
"status": 403,
5
"detail": "Your current balance is 30, but that costs 50.",
6
"instance": "/account/12345/msgs/abc",
7
"traceId": "7kHPSP_X0W1R0fo5h0fG",
8
"balance": 30,
9
"accounts": [
10
{
11
"owner": 587,
12
"path": "/account/12345"
13
},
14
{
15
"owner": 587,
16
"path": "/account/67890"
17
}
18
]
19
}
Copied!
Last modified 6mo ago