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.

Parameter	Type	Description
error.type	string	Broad class: `invalid_request_error`, `authentication_error`, `permission_error`, `idempotency_error`, `rate_limit_error`, `api_error`.
error.code	string	Stable machine-readable code, for example `member_not_found`. Branch on this, not on the message.
error.message	string	A sentence for the developer. It can change; do not parse it.
error.param	string	The request field the error is about, when there is one.
request_id	string	Also in the `X-Request-Id` header of every response. Include it when you write to us.

Status codes

Status	Meaning	What to do
200, 201	Success. 201 means something new was created.
400	The request is malformed or a field is invalid.	Fix the request. Retrying the same body gives the same answer.
401	No key, unknown key or revoked key.	Check the key.
402	The request was valid but cannot be done, for example not enough balance.	Show the guest the message; the body has the details.
403	The key lacks the scope this call needs.	Use a key with the scope named in the message.
404	The member, transaction, dish or order does not exist at this venue.	Check the identifier.
409	Conflict: 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`.
429	Too many requests.	Wait for `Retry-After` seconds.
500, 502, 503	Something failed on our side.	Retry with backoff and the same `external_id` or `Idempotency-Key`. Nothing is applied twice.

Common codes

Code	When
parameter_invalid	A field is missing or has the wrong format. See `param`.
member_not_found	No member matches the card number, barcode, phone or id.
card_number_taken	Another member at this venue already has this card number.
insufficient_balance	`redeem_amount` is more than the cashback balance. `available` has the balance.
redeem_not_supported	The member's program has no cashback balance to redeem.
visit_not_supported	A visit was sent for a cashback program. Send a check with an amount instead.
no_reward_available	The member has no earned reward to redeem.
transaction_not_found	No transaction with this `external_id`.
invalid_status_transition	The order cannot move from its current status to the one you sent.
missing_scope	The key does not have the required scope.
hold_required	The venue redeems cashback only through holds. Create one with `POST /v1/holds`.
hold_expired, hold_captured, hold_released	The hold can't be used any more. Create a new one.
register_id_required	The venue numbers checks per register, so `register_id` is required.
check_too_old	`closed_at` is older than the venue accepts.
scan_required	The venue accepts this only for a card this key scanned shortly before.
refund_exceeds_check	The refund is more than what is left of the check. `refundable` has the rest.
adjustments_disabled	The venue did not allow balance adjustments through the API.
idempotency_key_reused	The same `Idempotency-Key` was used with a different body.
rate_limited	Too many requests from this key.