Responses

Response Format

Unless otherwise indicated in the documentation for individual endpoints the Spaaza API responds with JSON - Content-Type: application/json.

Success

JSON showing a success response to a request:

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {}
}

If the HTTP request is successful the API will respond with a HTTP response code 200 and a “result” object in JSON showing a status of “ok”. This will be followed by a “results” section showing the results of the request.

Warnings

JSON showing an example warning inline in a success response

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "warnings": [
        {
            "code": 183,
            "name": "voucher_not_found",
            "description": "No voucher has been found matching this voucher_key or voucher_id.",
            "message": {
                "key": "0886407851fc56c6211f01abe1b4eab1fb1b48640efb73b1169c1d7a50e9467b"
            }
        }
    ],
    "results": {
    }
}

On some occasions a single or multiple warnings are returned as extra information supplementary to the main “results” in a 200 “ok” response, when the issue is not deemed to be of critical severity or when it is not desirable to interrupt the flow of the client. Warnings are returned in their own “warnings” array.

For example, when a transaction is being uploaded by a POS using the add-basket endpoint, but a voucher supplied is not recognised, it is still desirable to record the transaction in the Spaaza database because it has been paid for by the customer. In that case, a warning is added to the 200 “ok” response showing details of the unrecognised voucher.

A list of possible warning codes is found in the “Error and Warning Codes” section below.

Errors

JSON showing a sample error response to a request:

{
    "result": {
        "code": 2,
        "status": "error"
    },
    "error": {
        "code": 5,
        "name": "password_error_or_non_existent",
        "description": "Gebruikersnaam / wachtwoord zijn onbekend"
    }
}

If the response is an error, the API responds with an HTTP error response code and a “result” object showing a status of “error” - the call to the API endpoint is discontinued on generation of the error. This is followed by an “error” object in the response JSON showing the error response - there is only a single error returned.

In the case of an “error” response, no warnings are returned.

See the “error codes” section below for information on individual error codes.

In some cases more information may be supplied with the error to help identify the possible cause, such as a list of which characters are not allowed, or a hint on the format of a postal code.

Note that versions of the API previous to 1.4.0 returned a slightly different error structure. See the ‘Versioning’ section of the documentation. Documentation for older clients is available on request.