Read the error response
Check HTTP status before reading the result. statusCode repeats that status. error is a translation key for the general HTTP category, such as errors:http.conflict; it does not identify the business cause.
The Hallify HTTP error envelope includes a stable code: a domain code when available, or an HTTP_* fallback such as HTTP_UNAUTHORIZED. Use the status and documented code for program logic. Structured domain information may appear in details. Each operation documents its supported statuses and details.
message and translationKey contain the same stable translation key, never a rendered English or Russian sentence. Optional translationValues contains scalar data for placeholders. Translate the key in your application; the backend does not choose a display language and adding another language does not change the API payload.
validationErrors, when present, identifies each failing field with its validator code, key-only message and translationKey. Nested fields use dot-separated paths, including array indices. Match the field with the documented schema constraints. Submitted values and custom validator prose are not echoed.
The translation key catalog explains published keys using the same local translation resources as the Hallify client. Use your own translations when building another client. For unknown keys or missing translations, show a localized fallback; never display the key itself. Treat translationValues as plain data, not HTML or translation-library options.
Keep status/code for diagnosis without logging credentials or private payloads. An HTTP 409 alone does not mean a retry is safe. Unexpected or unregistered errors receive a standard key for their HTTP status and omit internal diagnostic text.
This envelope applies to responses emitted by the Hallify HTTP exception boundary. Successful acknowledgements, provider-specific callback protocols, streams that have already started, and infrastructure/proxy failures can have different formats. Follow the operation contract and check content type before parsing JSON. User-authored names, comments and other business content remain data.
{
"statusCode": 409,
"error": "errors:http.conflict",
"code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
"message": "errors:idempotency.inProgress",
"translationKey": "errors:idempotency.inProgress"
}Retry the same command safely
For operations requiring Idempotency-Key, create one key per logical command and retain it across network retries with the same payload. Reusing it with a different payload produces a conflict. Idempotency is operation-specific; it is not an automatic property of every POST.
For a revision conflict, read the current record and determine whether the intended action is still allowed. Do not blindly retry an expired quote, consumed bootstrap grant or invalid verification code.
Distinguish idempotency conflicts
These codes apply only to operations that document the shared idempotency conflict schema. Other integrations can use different conflict and replay protocols.
IDEMPOTENCY_REQUEST_IN_PROGRESS: an earlier request with this key is still processing. Wait, then retry with the same key and identical payload. A new key could execute the action twice.
IDEMPOTENCY_KEY_PAYLOAD_MISMATCH: the key belongs to a different payload. Restore the original payload for a retry. For a different business command, confirm the original outcome and assign a new key.
IDEMPOTENCY_REQUEST_NOT_READY: a stored result is not available yet. Retry with the original key and payload using a bounded backoff. Contact integration support if this persists.
IDEMPOTENCY_SCOPE_INCOMPLETE: the server could not resolve the required tenant or venue scope. Check the endpoint and documented context; contact integration support if they are correct. Do not repeatedly retry an unchanged request.
Recover the original reservation or agreement command
Keep create-intent/resend/verify receipts separate from currentState/current. A missing current enrichment or uncertain delivery is not failure of the committed command. Use read-intent for redacted current verification under its original context; a consumed intent cannot reissue a manage grant. Retry a lost command with the same key and exact body rather than starting a replacement booking or verification.
RESERVATION_GUARANTEE_TERMS_CHANGED requires a new review of exact native terms before a new deliberate action. RESERVATION_GUARANTEE_ACCEPTANCE_REQUIRED means the applicable original proof/digest is missing or unusable. RESERVATION_GUARANTEE_AGREEMENT_CHANGED or RESERVATION_GUARANTEE_REAGREEMENT_REQUIRED requires reading the actual current reservation/proposal and reviewing a valid agreement; never patch a stored hash, reprice an accepted obligation or bypass a deadline.
An original ACCEPTED agreement receipt can coexist with pending old refund/release, unresolved payment work or unavailable capacity. It does not prove ACTIVATED or restore a terminal reservation. manageAccessState: REPROOF_REQUIRED and currentState: UNAVAILABLE do not undo that acceptance or permit a second charge. Preserve the original command and use current authorized management and original payment recovery; hidden unavailability never permits resource probing or staff/account fallback.
Recover an original guest payment without replacing it
Guest payment admission and checkout have their own stable codes. GUEST_PAYMENT_INPUT_INVALID or INVALID_GUEST_PAYMENT_INPUT identifies malformed input. GUEST_PAYMENT_SOURCE_CHANGED, GUEST_PAYMENT_CONSENT_CHANGED or GUEST_PAYMENT_QUOTE_STALE requires inspecting current authority and the exact reviewed offer. Hidden unavailability does not authorize probing another resource, substituting account authentication or rewriting Origin.
After a lost create response, preserve the original command key and exact acceptance. POST commands/recover reads the first immutable PREPARED acknowledgement; GET checkout progress reads its current operation, funds and native application. These operations do not allocate a replacement command. Do not interpret acknowledgement PREPARED, a provider redirect or outcome query parameter as payment success.
POST checkout recovery is different: an explicit user action can acquire an original financial permit or replay the exact original Stripe CREATE when permitted. Do not call it automatically after reload/return. UNKNOWN, a retryable decline or a network error must retain the saved flow and unresolved holds; only proven server-terminal progress permits an explicit new payment.
No retry, unchanged offer or handoff refreshes the original financial deadline. Offers last at most five minutes; original financial access lasts at most fifteen minutes; own-receipt disclosure lasts at most twenty-four hours and remains bounded by current native/presentation authority. A receipt deadline cannot reopen spending or grant access to another checkout.
For widget transitions, save the original permit and receiver tuple before submission. Lost prepare/claim acknowledgements repeat the exact original proposal and retain the frozen expiry, including after consumption. Missing saved receiver state cannot be repaired with another tuple. A context/authority denial permits no cookie fallback, forged Origin or automatic replacement charge.
Respect limits and expiry
When the operation returns 429, respect Retry-After in whole seconds. Limits are configured by domain and channel; there is no single published quota shared by all integrations. Validate request sizes, array limits and field constraints in the reference.
A 401 can mean missing, invalid, expired or revoked access, or a stale signature. A hidden 404 can reflect resource scoping. For unavailable provider configuration, involve the restaurant administrator; do not change production data merely to test connectivity.