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

# Errors

> Every BrandWallet API error returns a JSON envelope with a stable machine-readable token in the message field. Reference all error codes here.

The BrandWallet API uses standard HTTP status codes. Every error response includes a JSON envelope with a stable, underscore-prefixed `message` token you can reliably match on in your integration code — these tokens do not change between API releases.

## Error response format

Every error response from the BrandWallet API returns the same JSON envelope:

<ResponseExample>
  ```json Error envelope theme={null}
  {
    "statuscode": 400,
    "errorcode": 400,
    "message": "_invalid_payload",
    "description": "",
    "timestamp": 1754040000000,
    "path": "/auth/token",
    "method": "POST"
  }
  ```
</ResponseExample>

<ResponseField name="statuscode" type="number">
  HTTP status code returned by the API.
</ResponseField>

<ResponseField name="errorcode" type="number">
  Internal error code. Matches `statuscode` in most cases.
</ResponseField>

<ResponseField name="message" type="string">
  Stable, machine-readable error token (underscore-prefixed). Use this field in your error-handling logic — it does not change between API versions.
</ResponseField>

<ResponseField name="description" type="string">
  Optional human-readable detail about the error. May be empty.
</ResponseField>

<ResponseField name="timestamp" type="number">
  Unix epoch timestamp in milliseconds indicating when the error occurred.
</ResponseField>

<ResponseField name="path" type="string">
  The API path that returned the error.
</ResponseField>

<ResponseField name="method" type="string">
  HTTP method of the request that triggered the error.
</ResponseField>

## Error token reference

| Token                               | Status | Meaning                                                                                         |
| ----------------------------------- | ------ | ----------------------------------------------------------------------------------------------- |
| `_invalid_payload`                  | 400    | Missing `x-api-key` or `x-api-secret` header on `/auth/token`                                   |
| `_invalid_credentials`              | 401    | The API key / secret pair is not valid                                                          |
| `_invalid_refresh_token`            | 400    | The refresh token is unknown, expired, or already rotated                                       |
| `_jwt_expired`                      | 401    | The access token has expired. Request a new one                                                 |
| `_jwt_malformed`                    | 401    | The access token is not a valid JWT                                                             |
| `invalid_filter_field`              | 400    | The `f[...]` field is not filterable on this endpoint. The description lists the allowed fields |
| `invalid_filter_value`              | 400    | The filter value is malformed (wrong type, empty, or below the minimum term length)             |
| `invalid_limit`                     | 400    | `limit` is not an integer between 1 and 250                                                     |
| `invalid_cursor`                    | 400    | `cursor` is not a cursor returned in `meta`                                                     |
| `_customer_not_found`               | 400    | No customer matches the given `q` term or customer id                                           |
| `_card_not_found`                   | 400    | The given `card` does not belong to the customer                                                |
| `_coupon_is_not_valid`              | 400    | The coupon is not redeemable (expired, disabled, or already redeemed)                           |
| `_insufficient_collectable_balance` | 400    | `pointsToSpend` exceeds the card's current point balance                                        |
| `_internal_server_error`            | 500    | Unexpected server error; retry later, contact support if it persists                            |

Validation errors on request bodies return `400` with the individual field messages joined in the `message` field.

## HTTP status code summary

BrandWallet uses conventional HTTP status codes to indicate the outcome of each request. `2xx` codes indicate success. `4xx` codes indicate a request error — inspect the `message` token and fix your request before retrying. `5xx` codes indicate a server-side error — wait briefly and retry, and contact BrandWallet at [dev@brand-wallet.com](mailto:dev@brand-wallet.com) if the condition persists.

<Tip>
  Always match on the `message` token in your error handling code, not on `statuscode` alone — the token is more specific and stable across API versions.
</Tip>

<Warning>
  If you receive `_internal_server_error` (500) repeatedly, contact BrandWallet at [dev@brand-wallet.com](mailto:dev@brand-wallet.com).
</Warning>