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.
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.