Error Handling

Best Practices

Client Errors

The vast majority of error responses received will have a status code of 422 Unprocessable Entity. Whenever this is returned, we will provide a general summary of the issue in the message field with further information available in additional fields that vary based on the error.

422 Responses

While you may re-word our responses within your application, we strongly recommend that you fall back to the content of the message field if the status code is 422, and you receive a response that you have not anticipated in your code. We endeavour to keep our integrating partners up to date with any and all changes to the API, however by falling back to the message field, you will need to update your code less frequently. This easily be implemented by returning the message field as the default return value of a match or switch/case expression. Please see below for a generic example.

 public function parseResponse($apiResponseWith422StatusCode) {
    return match($apiResponseWith422StatusCode->message) {
        'expectedResponse1' => 'customMessageFor1',
        'expectedResponse2' => 'customMessageFor2',
        'expectedResponse3','expectedResponse4' => 'customMessageFor3or4',
        default => $apiResponseWith422StatusCode->message
    };
 }

Server Errors

While we aim for server errors to be few and far between, it is best practice to assume that they will occur from time to time and have a response prepared.

5xx Responses

You can provide handling for each of the main 5xx errors, however a generic catch-all response for all 5xx errors will suffice.

5xx errors: In this case, something has gone wrong on our end. Further information is not provided in this instance so a 'Something went wrong' or 'Smart Gift was unable to process your request' response is appropriate here. We suggest using something like this for all 5xx errors with the possible exception of 503 responses.

503 errors: A 503 Service Unavailable response will be given at time when we are performing updates to the server that require us to block incoming requests. These periods are not frequent and generally do not last long, you may wish to return something like 'Smart Gift is temporarily unavailable, please try again in a few minutes', this may reduce unnecessary calls to support. Any planned downtime is usually set outside of most venues operating hours.