Client Error Examples

Note

In the responses shown here, the JSON that contains the error messages is pretty printed. The JSON in the actual responses returned by the API is terse and does therefore not contain newlines and indentation.

400 Bad Request

A bad request indicates that some of the arguments supplied by the client are incorrect. There are three main places where these arguments feature: the request body, as part of the path component, or as part of a query argument. The location key in the errors list indicates in which part of the request a particular request features.

Invalid Body

This is an example of posting an invalid receipt, in which all the required fields are left out. Information about missing fields are included in the response. If the JSON is invalid, a message to this effect will also be included in the errors list.

Request with invalid body

POST /receipts?key=...&signature=...&expires=... HTTP/1.1
Accept: application/json
Content-Length: 3
Content-Type: application/json
Host: api.ereceipts.co.uk

{}

Error response with body error

HTTP/1.1 400 Bad Request
Content-Length: 447
Content-Type: application/json; charset=UTF-8
Date: Mon, 27 Jun 2016 13:48:23 GMT

{
    "errors": [
        {
            "description": "items is missing",
            "location": "body",
            "name": "items"
        },
        {
            "description": "transaction_id is missing",
            "location": "body",
            "name": "transaction_id"
        },
        {
            "description": "localtime is missing",
            "location": "body",
            "name": "localtime"
        },
        {
            "description": "total is missing",
            "location": "body",
            "name": "total"
        },
        {
            "description": "store_reference is missing",
            "location": "body",
            "name": "store_reference"
        }
    ],
    "status": "error"
}

Invalid Query Arguments

Some resources, like that for getting a list of receipts take arguments in their query string. These may have to adhere to a specific format, as shown in this example.

Request using an invalid id in the query string

GET /receipts?id=INVALID&key=...&signature=...&expires=... HTTP/1.1
Accept: application/json
Host: api.ereceipts.co.uk

Error response with query argument error

HTTP/1.1 400 Bad Request
Content-Length: 128
Content-Type: application/json; charset=UTF-8
Date: Wed, 29 Jun 2016 14:59:52 GMT

{
    "errors": [
        {
            "description": "INVALID is not a valid receipt id",
            "location": "querystring",
            "name": "id.0"
        }
    ],
    "status": "error"
}

Invalid Path Arguments

Certain arguments that are passed as part of a URL have a specific format to which they must adhere. This is, for example, the case for the receipt id used when getting a receipt, as shown in this example.

Invalid argument in the path part of the URL

GET /receipts/INVALID?key=...&signature=....&expires=... HTTP/1.1
Accept: application/json
Host: api.ereceipts.co.uk

Error response with path argument error

HTTP/1.1 400 Bad Request
Content-Length: 119
Content-Type: application/json; charset=UTF-8
Date: Wed, 29 Jun 2016 14:17:52 GMT

{
    "errors": [
        {
            "description": "INVALID is not a valid receipt id",
            "location": "path",
            "name": "id"
        }
    ],
    "status": "error"
}

403 Forbidden

If there is any kind of authentication or authorisation error 403 Forbidden is returned.

Authentication error

This example shows an authentication error (i.e., a failure to prove who is accessing the API.) The subcode included in the response body indicates that authentication failed specifically due to an expired signature.

Request with expires time in the past

GET /receipts?key=...&signature=...&expires=0 HTTP/1.1
Accept: application/json
Host: api.ereceipts.co.uk

Forbidden error response

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=UTF-8
Date: Wed, 29 Jun 2016 11:37:54 GMT

{
    "code": "signature_expired",
    "description": "unauthorized: get_receipts failed permission check",
    "status": "forbidden"
}

Authorisation error

This example shows an authorisation error this could happen because the key that is being used does not have access to perform a certain kind of request, or a specific feature has not been enabled for this retailer (e.g., email sending.)

Request to a resource to which the used key does not have access

POST /email?key=...&signature=...&expires=... HTTP/1.1
Accept: application/json
Content-Length: 35
Content-Type: application/json
Host: api.ereceipts.co.uk

{
    "id": "507f191e810c19729de860ea"
}

Response indicating permission problem

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=UTF-8
Date: Wed, 29 Jun 2016 15:41:47 GMT

{
    "description": "e-mail sending not enabled",
    "status": "forbidden"
}

404 Not Found

A 404 Not Found error primarily occurs for two reasons, if attempting to use a resource that does not exist, e.g., because it has been misspelt; or if an element is requested that does not exist.

Misspelt resource name

In this example the word receipt, used to access the receipt resource has been spelt incorrectly.

Request with misspelt resource name

GET /reciepts?key=...&signature=...&expires=... HTTP/1.1
Accept: application/json
Host: api.ereceipts.co.uk

Not found error for a resource that does not exist

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=UTF-8
Date: Wed, 29 Jun 2016 15:15:22 GMT

{
    "description": "/reciepts",
    "status": "not found"
}

Non-existent element

A 404 Not Found also occurs when trying to fetch an element that does not exist, from a resource. This example shows the error returned when trying to fetch a receipt. The messages returned when getting an identifier, patching a loyalty identifier, etc that does not exist, is similar.

Requesting an element (a receipt in this case) that does not exist

GET /receipts/507f191e810c19729de860ea?key=...&signature=...&expires=... HTTP/1.1
Accept: application/json
Host: api.ereceipts.co.uk

Not found error for an element that does not exist

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=UTF-8
Date: Wed, 29 Jun 2016 15:13:51 GMT

{
    "description": "receipt 507f191e810c19729de860ea not found",
    "status": "not found"
}

405 Method Not Allowed

This example shows using the wrong method on a resource. The allowed methods are shown in the Allow header.

Wrong method used on the email resource

PATCH /email?key=...&signature=...&expires=... HTTP/1.1
Accept: application/json
Content-Length: 35
Content-Type: application/json
Host: api.ereceipts.co.uk

{
    "id": "507f191e810c19729de860ea"
}

Method not allowed error when using an unsupported method

HTTP/1.1 405 Method Not Allowed
Allow: POST
Content-Length: 32
Content-Type: application/json; charset=UTF-8
Date: Thu, 30 Jun 2016 10:09:06 GMT

{
    "status": "method not allowed"
}

406 Not Acceptable

This example shows a request that is being made with a value in the Accept header which the API will not accept.

Using an invalid Accept header when requesting a resource

GET /receipts?key=...&signature=...&expires=... HTTP/1.1
Accept: text/plain
Host: api.ereceipts.co.uk

Not acceptable error when using an unsupported accept header

HTTP/1.1 406 Not Acceptable
Content-Length: 143
Content-Type: application/json; charset=UTF-8
Date: Thu, 30 Jun 2016 10:15:54 GMT

{
    "errors": [
        {
            "description": "Accept header should be one of ['application/json']",
            "location": "header",
            "name": "Accept"
        }
    ],
    "status": "error"
}

409 Conflict

This example shows an attempt to submit a receipt with a duplicate transaction_id. The response body contains the existing receipt.

Submitting a duplicate transaction

POST /receipts?key=...&signature=...&expires=... HTTP/1.1
Accept: application/json
Content-Length: 387
Content-Type: application/json
Host: api.ereceipts.co.uk

{
    "transaction_id": "0011120008",
    "...": "..."
}

Conflict error is returned because a receipt with the transaction_id exists

HTTP/1.1 409 Conflict
Content-Length: 1118
Content-Type: application/json; charset=UTF-8
Date: Thu, 30 Jun 2016 11:23:00 GMT

{
    "id": "513e2391ee5e525ff9000000",
    "transaction_id": "0011120008",
    "...": "..."
}

This example shows an attempt to update a receipt which is still being processed by the API.

Updating an unprocessed receipt

PATCH /receipts/513e2391ee5e525ff9000000?key=...&signature=...&expires=... HTTP/1.1
Accept: application/json
Content-Length: 99
Content-Type: application/json-patch+json
Host: api.ereceipts.co.uk

[
    {
        "op": "add",
        "path": "/identifier",
        "value": "990000000001"
    }
]

Conflict error is returned because the receipt is still being processed

HTTP/1.1 409 Conflict
Content-Length: 70
Content-Type: application/json; charset=UTF-8
Date: Thu, 30 Jun 2016 11:23:00 GMT

{
    "description": "receipt processing is pending",
    "status": "conflict"
}

413 Payload Too Large

This example shows the result of submitting a payload that is larger than the API will accept, in this case the client accidentally sent a large binary file.

Submitting a large entity

POST /receipts?key=...&signature=...&expires=... HTTP/1.1
Accept: application/json
Content-Length: 8211835
Content-Type: application/octet-stream
Host: api.ereceipts.co.uk

... A lot of binary data ...

Request entity too large error when submitting too much data

HTTP/1.1 413 Request Entity Too Large
Content-Length: 192
Content-Type: text/html
Date: Thu, 30 Jun 2016 10:24:49 GMT

<html>
<head><title>413 Request Entity Too Large</title></head>
<body bgcolor="white">
<center><h1>413 Request Entity Too Large</h1></center>
</body>
</html>

This is an example of the Accept header that was sent with the request not being honoured (as the output is sent using text/html.)

415 Unsupported Media Type

This example shows the client attempting to submit data using XML where only JSON is supported. The API returns a list of acceptable Content-Types.

Attempting to post XML to the API

POST /receipts?key=...&signature=...&expires=... HTTP/1.1
Accept: application/json
Content-Length: 12
Content-Type: application/xml
Host: api.ereceipts.co.uk

<xml></xml>

Unsupported media type error when using wrong Content-Type

HTTP/1.1 415 Unsupported Media Type
Content-Length: 155
Content-Type: application/json; charset=UTF-8
Date: Thu, 30 Jun 2016 10:48:38 GMT

{
   "errors": [
       {
           "description": "Content-Type header should be one of ['application/json']",
           "location": "header",
           "name": "Content-Type"
       }
   ],
   "status": "error"
}

422 Unprocessable Entity

This example shows the client attempting to submit a receipt with a store reference which does not exist.

Attempting to post a receipt to the API with an invalid store reference

POST /receipts?key=...&signature=...&expires=... HTTP/1.1
Accept: application/json
Content-Length: 314
Content-Type: application/json
Host: api.ereceipts.co.uk

{
    "items": [
        {
            "name": "Small Shoes",
            "quantity": 3,
            "total": 961.75
        }
    ],
    "localtime": "2019-05-07T10:00:22+02:00",
    "timestamp": "2019-05-07T08:00:22.990Z",
    "store_reference": "100",
    "total": 961.75,
    "transaction_id": "581177999498"
}

Unprocessable entity error when using an invalid store reference

HTTP/1.1 422 Unprocessable Entity
Content-Length: 72
Content-Type: application/json
Date: Tue, 07 May 2019 08:08:46 GMT

{
    "description": "store 100 not found",
    "status": "unprocessable entity"
}

429 Too Many Requests

Clients may be rate limited when making too many requests within a given time. Rate limited requests will return a 429 code and should be retried at some later date. The returned content may depend on the Accept header.

Too many requests error returning JSON

HTTP/1.1 429 Too Many Requests
Content-Length: 97
Content-Type: application/json
Date: Tue, 07 May 2019 08:08:48 GMT

{
    "description": "Rate limited due to too many requests",
    "status": "too many requests"
}

Too many requests error returning HTML

HTTP/1.1 429 Too Many Requests
Content-Length: 108
Content-Type: text/html
Date: Tue, 07 May 2019 08:08:49 GMT

<html>
<head><title>429 Too Many Requests</title></head>
<body>
<h1>429 Too Many Requests</h1>
<p>Rate limited due to too many requests</p>
</body>
</html>