Skip to main content
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
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 credential, while a 403 response indicates the credential does not have permission to perform the requested action.
Example
Two of these carry a machine-readable code, and both apply only to requests authenticated with a customer session token:
  • token_expired, a 401. The session token is past its expiry. Issue a fresh one and retry the request once.
  • insufficient_scope, a 403. The session token is valid, but was issued without a scope the endpoint requires. Retrying won’t help; the fix is in the code that issues the token.
Example
Every other session token 401 carries no code, but most include a tag such as [INVALID_SIGNATURE] in the message, naming the check that failed. The tags, and the remaining code-less 403 rejections, are listed on the customer session tokens page.

​
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

​
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

​
Rate limit errors - 429

If your API key has exceeded its rate limit, a 429 response will be returned. Requests authenticated with a customer session token are limited per customer instead, so one shopper cannot exhaust the budget for the rest of your site.