Our API returns standard HTTP status codes.

Successful requests

We use Hypertext Application Language (HAL) (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 (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.

Notes:

If needed, the Problem Detail may include additional fields, refer to RFC7807 for details.
title and detail fields should not be parsed to determine the nature of the error.

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.

{
    "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 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:

{  
...
  "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).