Headless API endpoints return can various errors. As a general rule, only 422 errors represent a problem that could be relayed to the shopper. All other error responses represent either a bug in your integration, an authentication issue, or a rate limit being reached.

​
Validation errors - 400

If your request fails structural validation, a 400 response will be returned, with details about the problematic fields. For example, the channel query parameter requires one of web, pos or mobile. If you provide a different value, you’ll receive an error like this:
Example
{
  "error": {
    "message": "Invalid request",
    "details": {
      "channel": "Invalid option: expected one of \"web\"|\"pos\"|\"mobile\""
    }
  }
}
These kind of error responses represent a bug in your integration; the error itself is not useful to a shopper, or suitable to show to them.

​
Authentication errors - 401, 403

These errors will be returned if your request could not be authenticated. In general, a 401 response indicates an invalid API key, while a 403 response indicates the API key does not have permission to perform the requested action.
Example
{
  "error": {
    "message": "Authentication is required"
  }
}

​
Not found errors - 404

If you request a resource that does not exist, a 404 response will be returned. For example, if you redeem a reward and pass a reward_id or a customer_merchant_id that does not exist in LoyaltyLion, a 404 response will be returned.
Example
{
  "error": {
    "code": "not_found",
    "message": "Reward with ID `1000` not found"
  }
}

​
Unprocessable errors - 422

If your request was correct, but it cannot be processed, a 422 response will be returned. This kind of error will always have a code, and each API endpoint’s documentation page which error codes to expect, and what they mean. For example, if you redeem a reward but it is out of stock, a reward_out_of_stock code will be returned. You should review the expected error codes, determine which will apply to your integration, and turn them into an appropriate shopper-facing error message.
Example
{
  "error": {
    "code": "reward_out_of_stock",
  }
}

​
Rate limit errors - 429

If your API key has exceeded its rate limit, a 429 response will be returned.