Errors

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:

{
  "statuscode": 400,
  "errorcode": 400,
  "message": "_invalid_payload",
  "description": "",
  "timestamp": 1754040000000,
  "path": "/auth/token",
  "method": "POST"
}

number

HTTP status code returned by the API.

number

Internal error code. Matches statuscode in most cases.

string

Stable, machine-readable error token (underscore-prefixed). Use this field in your error-handling logic — it does not change between API versions.

string

Optional human-readable detail about the error. May be empty.

number

Unix epoch timestamp in milliseconds indicating when the error occurred.

string

The API path that returned the error.

string

HTTP method of the request that triggered the error.

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 if the condition persists.

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.

If you receive _internal_server_error (500) repeatedly, contact BrandWallet at dev@brand-wallet.com.

Getting started

Endpoints

Reference

Error response format

Error token reference

HTTP status code summary

​Error response format

​Error token reference

​HTTP status code summary

Error response format

Error token reference

HTTP status code summary