Error Handling
When a problem occurs during request processing, the Transact API returns standard HTTP status codes. Some examples:
- A request to a nonexistent endpoint returns a
404 Not Found. - An unauthenticated request returns a
401 Unauthorized. - A malformed request returns a
400 Bad Request. - Exceeding a rate limit returns a
429 Too Many Requests.
Problem response body
While some simple problems do not need any additional context, in most instances the Transact API will also return a RFC 9457-compliant JSON object in the response body with detailed diagnostic information. The JSON object contains the following fields:
| Field | Description |
|---|---|
type | The unique identifier for the problem type. |
title | A human-readable summary of the problem type. |
detail | A human-readable description of this occurrence of the problem. |
status | The HTTP status code corresponding to the problem. |
request_id | The unique ID for the request, used for troubleshooting. |
errors | Individual errors contributing to the overall problem (optional). |
The type, title, and status fields are common to all instances of the problem.
For information about a specific occurrence, the detail field and errors field (if present) can be inspected.
Note that detail and errors are designed for human consumption, not machine parsing, and are subject to change
without notice.
As an example, see this sample response to an invalid request:
Problem Details JSON object example
Problem types
The Transact API currently returns the following problem types. Note that new problem types may be added at any time without notice.
| Problem type | Status | Description |
|---|---|---|
/problems/malformed_request | 400 | The request was malformed (e.g. JSON syntax errors). |
/problems/invalid_request | 400 | The request failed schema validation (e.g. missing fields, invalid values, etc.). |
/problems/business_rule_violation | 400 | The request failed business rule validation. |
/problems/forbidden_role | 403 | This endpoint is not available for the Resource Owner's user type. |
/problems/resource_not_found | 404 | The requested resource could not be found. |
/problems/invalid_api_version | 406 | A valid Transact-Api-Version header was not supplied. |
/problems/rate_limit_exceeded | 429 | A rate limit was exceeded (see Rate Limits). |
/problems/server_error | 500 | The server encountered an unexpected error. |
/problems/server_maintenance | 503 | The server is currently under maintenance. |
Authentication errors
Authentication errors are usually due to the access token being insufficient, revoked, or improperly supplied. In these cases the Transact API does not return a problem response body.
For these errors, the WWW-Authenticate response header is used in compliance with
RFC 6750.
This header contains the authentication scheme (always Bearer) and optional further attributes in the form
attr1="value1", attr2="value2, ...". The error attribute can be used to disambiguate different types of error as
seen below.
Common authentication error cases and their corresponding WWW-Authenticate response headers are listed below.
| Status | error | Cause |
|---|---|---|
| 401 Unauthorized | Not provided | The access token has not been correctly supplied using the HTTP Bearer scheme (Authorization: Bearer <token>). |
| 401 Unauthorized | "insufficient_scope" | The access token does not meet the scope requirements for this endpoint. The scope attribute contains the required scopes (space-separated). |
| 401 Unauthorized | "invalid_token" | The access token is no longer valid. The error_description attribute contains the specific reason. You should acquire a new access token by using your refresh token or prompting the user to reauthorise. |
Reporting errors
Please Contact Us, making sure to include the request ID. This can be found in:
- the
Request-Idresponse header, for all responses - the
request_idproblem response body field (when a problem occurs).
Please also include:
- the request headers
- the request body (if applicable)
- the received response body
- any other useful context that you can provide.