☰ Menu · Errors
Getting started

Errors

HTTP status codes say what kind of problem it is; the JSON body says exactly what and, when it is about one field, which one.

JSON
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "consent: must be true: confirm the guest agreed to data processing",
    "param": "consent"
  },
  "request_id": "req_0d4d15b86c484738b46b"
}
error.typestring
Broad class: invalid_request_error, authentication_error, permission_error, idempotency_error, rate_limit_error, api_error.
error.codestring
Stable machine-readable code, for example member_not_found. Branch on this, not on the message.
error.messagestring
A sentence for the developer. It can change; do not parse it.
error.paramstring
The request field the error is about, when there is one.
request_idstring
Also in the X-Request-Id header of every response. Include it when you write to us.

Status codes

StatusMeaningWhat to do
200, 201Success. 201 means something new was created.
400The request is malformed or a field is invalid.Fix the request. Retrying the same body gives the same answer.
401No key, unknown key or revoked key.Check the key.
402The request was valid but cannot be done, for example not enough balance.Show the guest the message; the body has the details.
403The key lacks the scope this call needs.Use a key with the scope named in the message.
404The member, transaction, dish or order does not exist at this venue.Check the identifier.
409Conflict: card number taken, status change not allowed, or the balance changed during the call.Read the code. For balance_conflict, retry with the same external_id.
429Too many requests.Wait for Retry-After seconds.
500, 502, 503Something failed on our side.Retry with backoff and the same external_id or Idempotency-Key. Nothing is applied twice.

Common codes

CodeWhen
parameter_invalidA field is missing or has the wrong format. See param.
endpoint_not_foundNo endpoint at this path. Check the method and the path against this reference.
member_not_foundNo member matches the card number, barcode, phone or id.
card_number_takenAnother member at this venue already has this card number.
insufficient_balanceredeem_amount is more than the cashback balance. available has the balance. max_amount is the most this check can redeem and limited_by says which limit applies.
redeem_not_supportedThe member's program has no cashback balance to redeem.
visit_not_supportedA visit was sent for a cashback program. Send a check with an amount instead.
no_reward_availableThe member has no earned reward to redeem.
transaction_not_foundNo transaction with this external_id.
invalid_status_transitionThe order cannot move from its current status to the one you sent.
missing_scopeThe key does not have the required scope.
hold_requiredThe venue redeems cashback only through holds. Create one with POST /v1/holds.
hold_expired, hold_captured, hold_releasedThe hold can't be used any more. Create a new one.
register_id_requiredThe venue numbers checks per register, so register_id is required.
redeem_not_allowed_hereCashback cannot be redeemed at the location this register_id is bound to. Send the check with redeem_amount 0 (the guest still earns), or redeem at another location.
discount_redeem_not_allowedCashback cannot be redeemed on a check with this discount_type: the owner forbade paying with cashback for this discount. Send the check with redeem_amount 0 (the guest still earns, if the type allows).
check_too_oldclosed_at is older than the venue accepts.
scan_requiredThe venue accepts this only for a card this key scanned shortly before.
refund_exceeds_checkThe refund is more than what is left of the check. refundable has the rest.
adjustments_disabledThe venue did not allow balance adjustments through the API.
idempotency_key_reusedThe same Idempotency-Key was used with a different body.
rate_limitedToo many requests from this key.
Questions about an integration: api@loyaltyfy.io. We answer within one business day.