> ## Documentation Index
> Fetch the complete documentation index at: https://developers.loyaltylion.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

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:

```json Example theme={null}
{
  "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.

```json Example theme={null}
{
  "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](/2025-06/reward-redemption/cart-discount-voucher)
and pass a `reward_id` or a `customer_merchant_id` that does not exist in LoyaltyLion,
a `404` response will be returned.

```json Example theme={null}
{
  "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](/2025-06/reward-redemption/cart-discount-voucher)
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.

```json Example theme={null}
{
  "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.