# 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](https://www.rfc-editor.org/rfc/rfc9457.html)-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:

```json title="Problem Details JSON object example"
{
  "type": "/problems/invalid_request",
  "title": "Invalid Request",
  "detail": "Request body does not match JSON schema",
  "status": 400,
  "request_id": "8c25076679d0339b273037447ab26aea",
  "errors": [
    {
      "pointer": "#",
      "detail": "required property 'investors' not found"
    },
    {
      "pointer": "#/bank_account/sort_code",
      "detail": "does not match the regex pattern ^\\d{6}$"
    }
  ]
}
```

## 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](rate-limiting.md)).                  |
| `/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](https://datatracker.ietf.org/doc/html/rfc6750).
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](../getting-started/authorisation.md#using-a-refresh-token) or prompting the user to [reauthorise](../getting-started/authorisation.md#acquiring-an-access-token). |

## Reporting errors

Please [Contact Us](../contact-us.mdx), **making sure to include the request ID**. This can be found in:

- the `Request-Id` response header, for all responses
- the `request_id` problem 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.