# Successful requests

We use [Hypertext Application Language (HAL)](https://datatracker.ietf.org/doc/html/draft-kelly-json-hal-06) (`application/hal+json`) for successful responses (`2xx`). HAL is a standard that establishes conventions for expressing hypermedia controls, specifically through the use of `_links` and `_embedded` properties. Use these links to request more information about and construct an API flow that is relative to a specific request.

| Status code | Description |
| --- | --- |
| `200 OK` | The request succeeded. |
| `201 Created` | A POST method successfully created a resource. If the resource was already created by a previous execution of the same method, for example, the server returns the HTTP 200 OK status code. |
| `202 Accepted` | The server accepted the request and will execute it later. |
| `204 No Content` | The server successfully executed the method but returns no response body. |

# Failed requests

We follow the [Problem Details](https://datatracker.ietf.org/doc/html/rfc7807) (`application/problem+json`) for error responses. This is a standard format for HTTP status codes `4xx` and `5xx`. By definition, all responses contain a `title` and `detail` properties. Some requests may have additional properties.

| Property | Type | Description |
| --- | --- | --- |
| `title` | `string` | Human-readable summary of the problem type. It doesn't change from occurrence to occurrence of the problem. |
| `detail` | `string` | Human-readable explanation specific to this occurrence of the problem. |

## 4xx status codes

| Status code | Description |
| --- | --- |
| `400 Bad Request` | The request is not well-formed, syntactically incorrect, or violates schema. |
| `404 Not Found` | The specified resource does not exist. |
| `405 Method Not Allowed` | The server does not implement the requested HTTP method. |
| `409 Conflict` | The request cannot be processed as it conflicts with another request. |
| `413 Content Too Large` | The request entity is larger than the limits defined by the server. |
| `422 Unprocessable Entity` | The request is well formatted but it fails some business logic validation |
| `429 Too Many Requests` | The rate limit for the user, application, or token exceeds a predefined value. |

### Validation errors

A Problem Detail response may include additional error details about the problems that have occurred. These can be found under the errors collection and follow the Problem Details structure.

```json
{
  "title": "Bad Request",
  "detail": "Request failed validation",
  "errors": [
    {
      "title": "invalid_type",
      "detail": "`body.name` is `undefined`, but `string` is expected."
    }
  ]
}
```

## 5xx status codes

| Status code | Description |
| --- | --- |
| `500 Internal Server Error` | An internal server error has occurred. |
| `501 Not Implemented` | The server does not support the functionality required to fulfill the request. |
| `503 Service Unavailable` | Service Unavailable. |

# Authorization errors

We follow industry-standard [OAuth 2.0 authorization protocol](https://datatracker.ietf.org/doc/html/rfc6749) and return the HTTP `401`, and `403` status code for authorization errors.

| Status code | Description |
| --- | --- |
| `401 Unauthorized` | The client request has not been completed because it lacks valid authentication credentials for the requested resource. _This may happen when credentials are incorrect or invalid (e.g. expired)._ |
| `403 Forbidden` | The server understands the request but refuses to authorize it. _Occurs when the credentials are valid but don't have required permissions._ |

# Data Representation

## Null

**null** is used to represent the absence of a value. The response structure preserves known attributes even when it has no value associated with it. In case an attribute value is not known it's represented as `null`.

Example of a transaction message representation, with unknown attributes on the acceptor field:

```text
{
  ...
  "acceptor": {
    "acquirerId": null,
    "city": "LONDON",
    "country": "GBR",
    "id": "KWGBYTEI4FL0QQQ",
    "mcc": null,
    "name": null,
    "state": null
  },
  ...
}
```

## Addition of new fields

The addition of new fields to API responses **is not considered a breaking change**. Therefore, we do not recommend that consumers perform strict validation on the payload (i.e., disallowing unknown fields).