Errors

The error envelope and every contract code.

Pilotv1

Branch on error.code, never on the message. Statuses follow HTTP: 4xx means the request should change, 429 and 503 mean retry later, 5xx means retry with the same Idempotency-Key. A refusal changes nothing.

Beyond the codes below you will meet VALIDATION (422, with fieldErrors), RATE_LIMITED (429, a per-route limit), FEATURE_REQUIRED (403, the plan lacks a feature), INTERNAL (500) and a few named on their own routes.

Codes

Code	Status	Meaning
`INVALID_CREDENTIAL`	401	missing, malformed, unknown, expired or revoked. One code, one message, so nothing leaks.
`PLAN_REQUIRED`	402	the business has not paid yet.
`DEVELOPER_API_NOT_ENABLED`	403	pilot mode and this business is not on the allowlist.
`INSUFFICIENT_SCOPE`	403	this key lacks the scope the route needs.
`SUSPENDED`	403	the business is paused by Revisit support and the call writes.
`TEST_MODE_BLOCKED`	403	test mode asked for a real provider (SMS, push, wallet, payment); nothing real is ever sent from a test workspace.
`NOT_FOUND`	404	unknown id, an id of another business, or the API switched off.
`BENEFIT_RESERVED`	409	part of the balance is held by a checkout reservation, so a counter or API spend would leave a hold unfunded. Nothing changed; confirm or release the hold, or let it expire.
`CUSTOMER_REFERENCE_CONFLICT`	409	the customer id or the phone points at a different customer than the one this request would create or change. Nothing is merged or moved.
`IMPORT_NOT_FINISHED`	409	a retry was asked of an import that is still queued or running.
`INSUFFICIENT_AVAILABLE`	409	not enough is available (the balance less active holds) to hold or spend this. Nothing changed.
`NOT_A_STAMP_CARD`	409	the card no longer collects stamps, so a waiting stamp cannot be added. Nothing changed.
`OPERATION_IN_PROGRESS`	409	the first request with this operation key is still running. Retry the same request shortly.
`OPERATION_KEY_CONFLICT`	409	the same operation key arrived with different content. The key is still bound to the first request.
`PENDING_DECIDED`	409	someone (staff, or this or another application) already confirmed or rejected this pending self-stamp. The decision is final and nothing changed.
`PENDING_EXPIRED`	409	the pending self-stamp was not decided within 24 hours, so it has ended. Nothing was stamped.
`RESERVATION_EXPIRED`	409	the reservation ran out before it was confirmed. Nothing was spent: reconcile the checkout (refund the payment, or reserve again).
`RESERVATION_NOT_ACTIVE`	409	the reservation is already in another terminal state (confirmed, or released) than this call needs.
`REVERSAL_BENEFIT_USED`	409	the customer has already used the stamps or points the earning gave, so taking them back would leave a negative balance or undo a spent reward. The original earning stays in force and nothing changed; the owner decides (owner review).
`REVERSAL_CONFLICT`	409	this reversalId was already used for a different request (another earning, amount or customer). Nothing changed.
`REVERSAL_EXCEEDS_ORIGINAL`	409	a reversal would take back more of the earning than is left (it is already fully reversed, or the refund is larger than what remains). Nothing changed.
`REVERSAL_REVIEW_RESOLVED`	409	the owner already decided this reversal review; the decision is final.
`SOURCE_EVENT_CONFLICT`	409	this source event id was already applied with different content (another customer, program, action or amount). Nothing changed.
`TEAM_MEMBER_LIMIT`	409	this business reached its existing membership/licence cap.
`TEAM_STATE`	409	a team invitation or membership cannot enter the requested state.
`WALLET_NOT_CONFIGURED`	409	the wallet asked for (Apple or Google) is not set up on this deployment. Nothing was created.
`DISPLAY_EXPIRED`	410	the display file is gone (its day passed). Generate a new one.
`EXPORT_EXPIRED`	410	the export file is gone (its day passed, or a customer in it was erased). Make a new export.
`CURRENCY_MISMATCH`	422	a money action named a currency other than the program's. Nothing changed.
`DISPLAY_NO_LINK`	422	the card or branch has nothing to print (no active branch with a join link).
`EXPORT_TOO_LARGE`	422	more customers match than one export holds; narrow it by program or branch.
`OPERATION_KEY_REQUIRED`	422	a business-changing request has no usable `Idempotency-Key` header. The key is not consumed.
`UNSUPPORTED_ACTION`	422	the action is not one a service may take (top-up, spend, set or adjust a balance, void) or the program's card type does not take earning and redeeming from the API yet. Nothing changed.
`UNSUPPORTED_CURRENCY`	422	the gift card design names a currency this API does not handle (see the currency list). Nothing was issued.
`DEVELOPER_RATE_LIMITED`	429	a shared business or credential request/concurrency budget is full.
`DISPLAY_BACKLOG`	429	the business already holds the most ready displays it may; wait for one to expire.
`DISPLAY_BUSY`	429	the generator is busy (too many displays being made, or this one took too long). Nothing was stored and the Idempotency-Key is free: retry after the delay.
`EXPORT_BACKLOG`	429	the business already holds the most ready exports it may; wait for one to expire.
`IMPORT_BACKLOG`	429	the business already has the most customer imports waiting or running it may have. Nothing was queued; retry when one finishes.
`DEVELOPER_LIMITER_UNAVAILABLE`	503	shared public admission is not configured or Redis is unavailable.

Codes#

Codes