Error and Success Codes¶

The API uses the standard HTTP response codes to communicate error conditions as well as successful requests to the client. Additionally, an optional subcode may be included in the response body to indicate a specific error condition.

Error Codes¶

The error code returned to the client depends on whether the client sent incorrect input (resulting in a 4xx error) or whether the API has encountered an internal error (resulting in a 5xx error.) Additionally, any proxies and load-balancers that might sit in-between the client and the API may also produce error codes that the API has no control over.

Further resources describing HTTP error codes that may be returned by the API or proxies:

4xx: The Client has Caused an Error¶

When returning client (4xx) error codes, the API will attempt to provide a human readable description of the error condition in a JSON object. The Client Error Examples section contains some concrete examples of what error responses might look like. As the bodies in 4xx responses are informational and generally meant for human consumption the Content-Type of the body does not necessarily honour the formats requested in the Accept header.

400 Bad Request (example)

This error code is returned when none of the 4xx error codes below can be used to better describe the error condition. This code would be returned, for example, if the posted JSON is not syntactically correct; or if syntactically valid JSON does not include all the required fields, for example, when posting a receipt.

403 Forbidden (example)

This error code is returned either when authentication has failed, which could be due to one of the following:

An invalid key,
A revoked key,
A timed out signature - indicated by the signature_expired subcode,
A signature over the upper limit of expiry - signature_too_far_in_the_future subcode,
An incorrectly calculated signature,

and is also returned if the key used for authentication does not have permissions to access a particular resource.

Note

If you get a 403 Forbidden error, please check that the clock on the machine from which you are making request is set correctly, that the key used is correct, and that the signature algorithm is implemented correctly (see the section on Authentication.)

404 Not Found (example)

This error code is returned when a resource cannot be found. This might happen, for example, when attempting to get a receipt that does not exist or attempting to get an identifier that does not exist.

405 Method Not Allowed (example)

This error code is returned if you use the wrong HTTP method on a resource, such as using PATCH with the receipt sending resource which only supports POST.

406 Not Acceptable (example)

This error code is returned when making a request with an Accept header that is not valid. For example, using an Accept: text/html header for a resource that only supports application/json. The response will contain a description of valid Accept header values.

409 Conflict (examples)

This error code is returned on:

POST if the entity already exists. For example, a receipt posted with a duplicate transaction_id will be rejected with this error code.
PATCH if the entity cannot be altered for various reasons. This might happen, for example, if trying to update a receipt and the receipt in question has not yet been processed fully by the API; or if, for example, an attribute of an entity cannot be altered such as updating a loyalty identifier to an invalid value.

413 Payload Too Large (example)

This error code is returned on POST, PUT, or PATCH requests when the request body uploaded to the API is too large to be accepted.

415 Unsupported Media Type (example)

This error code is returned on a POST, PATCH, or PUT when the Content-Type header is incorrect. For example, if trying to post XML using a Content-Type: application/XML header (as the API does not support XML.)

422 Unprocessable Entity (example)

This error code is returned on POST, PATCH, or PUT if the syntax of the data is correct, but it contains a reference to something that does not exist. For example when posting a receipt with a store reference that is not valid.

429 Too Many Requests (example)

This error code is returned when too many requests have been made to the API in a given amount of time and the client is being rate limited. The client should slow down its rate of requests. Any requests that result in a 429 will not have completed and should be retried, for non-idempotent requests (for example: posting a receipt, sending an email receipt, etc) this is especially important.

5xx: An Error Happened in the API¶

500 Internal Server Error: The API encountered an internal error that makes it unable to complete the request.
501 Not Implemented: The API does not implement the particular feature that is being requested.
503 Service Unavailable: This code is returned when the API is unable to complete the request at the moment and you may try again later. This is most likely to happen when the API is using a 3rd party service that is not currently available.

Codes for Successful Requests¶

Successful requests will return a code in the range 2xx. Generally this will be one of the following:

200 OK: This code is returned when a request completed successfully and none of the codes below are applicable. Some form of content will be returned with the response, such as when getting an existing receipt.
201 Created: This code is returned when a request successfully creates a new entity. Some additional information, such as the ID of the new entity, may also be returned. This code is, for example, used when posting a new receipt.
204 No Content: This code is returned when a request completed successfully, but there is no content to return. This happens, for example, when patching an identifier or when verifying a card.