Skip to content
HallifyDevelopersSearch documentation
Open Hallify
Sections

Guest payments

Recover the original guest checkout

POST/public/guest-payment-accesses/{accessId}/restaurant-payments/checkouts/{checkoutId}/recover

Continues the existing checkout after current exact-resource disclosure authorization. Previously dispatched bank operations and dispatched operations with a surviving provider locator use retained SYSTEM readback and admitted native application. An unsent original, or the exact original Stripe CREATE replay inside its existing idempotency window when no locator survived, requires current spending authority, all original payment targets under canonical native locks and a one-shot frozen-request permit within the saved financial deadline. No replacement Core command is allocated, and UNKNOWN or a retryable decline alone cannot release holds.

Authentication

Authorization: Bearer <HALLIFY_GUEST_PAYMENT_ACCESS_TOKEN>

Private guest payment capability bound to its native actor, tenant, source, transport origin and current authority. Explicit consent is required for collection; exact original receipt disclosure does not grant a new monetary command or a Hallify account session.

Connection guide

Parameters

originHeader · Required

Actual HTTP Origin of the caller, which must exactly match the payment access's current transport audience.

string
Full definition
{
  "type": "string",
  "maxLength": 2048,
  "example": "example"
}
accessIdPath · Required

Noncredential UUID returned when native payment access is opened or handed off. Pair it with that access's bearer capability; the UUID alone grants no authority.

string · uuid
Full definition
{
  "format": "uuid",
  "type": "string",
  "example": "9b6163a8-afea-4877-818b-8e2ae28a2845"
}
checkoutIdPath · Required

UUID of the existing original checkout to recover; its retained consent and permanent Core command determine the provider operation and frozen request.

string · uuid
Full definition
{
  "format": "uuid",
  "type": "string",
  "example": "9b6163a8-afea-4877-818b-8e2ae28a2845"
}

Responses

200Current original-checkout progress after the permitted recovery attempt; it may remain pending, unknown or reconciliation-required, with the original acknowledgement preserved.
GuestPaymentProgressDto
Full definition
{
  "$ref": "#/components/schemas/GuestPaymentProgressDto"
}
Example response · 200 · application/json
{
  "receipt": {
    "schema": "hallify.restaurant-payment.command-result",
    "version": 1,
    "checkoutId": "f5ef2bdc-76ae-45b6-851a-399882860529",
    "operationId": "44352441-86e0-4a70-8642-d5863bea459a",
    "action": "CREATE_CHECKOUT",
    "state": "PREPARED",
    "currency": "USD",
    "principalAmount": "12.50",
    "tipAmount": "0.00",
    "totalAmount": "12.50"
  },
  "checkoutId": "f5ef2bdc-76ae-45b6-851a-399882860529",
  "operationId": "44352441-86e0-4a70-8642-d5863bea459a",
  "state": "PREPARED",
  "fundsState": "1.000",
  "applicationState": "example",
  "terminal": true,
  "retryAt": null,
  "provider": {
    "redirectUrl": null,
    "expiresAt": null
  }
}
400The bounded request or command key is malformed.
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 400 · application/json
{
  "statusCode": 400,
  "error": "errors:http.badRequest",
  "code": "HTTP_BAD_REQUEST",
  "message": "errors:http.badRequest",
  "translationKey": "errors:http.badRequest"
}
401Rejects a missing, malformed, expired, revoked, or invalid guestPaymentAccessToken credential at the owning domain boundary.
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 401 · application/json
{
  "statusCode": 401,
  "error": "errors:http.unauthorized",
  "code": "HTTP_UNAUTHORIZED",
  "message": "errors:http.unauthorized",
  "translationKey": "errors:http.unauthorized"
}
404Current native authority, private payment capability or the exact original checkout is unavailable.
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 404 · application/json
{
  "statusCode": 404,
  "error": "errors:http.notFound",
  "code": "HTTP_NOT_FOUND",
  "message": "errors:http.notFound",
  "translationKey": "errors:http.notFound"
}
409The native source, reviewed bill, consent revision or concurrent command state changed.
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 409 · application/json
{
  "statusCode": 409,
  "error": "errors:http.conflict",
  "code": "HTTP_CONFLICT",
  "message": "errors:http.conflict",
  "translationKey": "errors:http.conflict"
}

Schemas

GuestPaymentProgressDto

Current original-checkout operation, funds, native application and navigation progress together with its immutable first acknowledgement, disclosed under current exact-resource native authority.

receiptRequired

Immutable first PREPARED acknowledgement for this checkout, retaining the original command, operation and accepted monetary amounts.

allOf
Full definition
{
  "description": "Immutable first PREPARED acknowledgement for this checkout, retaining the original command, operation and accepted monetary amounts.",
  "allOf": [
    {
      "$ref": "#/components/schemas/GuestPaymentCommandReceiptDto"
    }
  ],
  "example": {
    "schema": "hallify.restaurant-payment.command-result",
    "version": 1,
    "checkoutId": "f5ef2bdc-76ae-45b6-851a-399882860529",
    "operationId": "44352441-86e0-4a70-8642-d5863bea459a",
    "action": "CREATE_CHECKOUT",
    "state": "PREPARED",
    "currency": "USD",
    "principalAmount": "12.50",
    "tipAmount": "0.00",
    "totalAmount": "12.50"
  }
}
checkoutIdRequired

UUID of the exact original checkout authorized for this disclosure.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "description": "UUID of the exact original checkout authorized for this disclosure.",
  "example": "f5ef2bdc-76ae-45b6-851a-399882860529"
}
operationIdRequired

UUID of the original CREATE_CHECKOUT provider operation whose current state is reported.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "description": "UUID of the original CREATE_CHECKOUT provider operation whose current state is reported.",
  "example": "44352441-86e0-4a70-8642-d5863bea459a"
}
stateRequired

Current state of the original provider operation. Funds and native financial application progress are reported in their dedicated fields.

string
Full definition
{
  "type": "string",
  "enum": [
    "PREPARED",
    "DISPATCHING",
    "PENDING",
    "UNKNOWN",
    "SUCCEEDED",
    "REJECTED",
    "RECONCILIATION_REQUIRED"
  ],
  "description": "Current state of the original provider operation. Funds and native financial application progress are reported in their dedicated fields.",
  "example": "PREPARED"
}
fundsStateRequired

Current stored checkout funds projection, including unresolved or unknown provider evidence and admitted later financial operations.

string
Full definition
{
  "type": "string",
  "description": "Current stored checkout funds projection, including unresolved or unknown provider evidence and admitted later financial operations.",
  "example": "1.000"
}
applicationStateRequired

Current native financial application state for the checkout, including pending, applied, blocked or reconciliation-required owner effects.

string
Full definition
{
  "type": "string",
  "description": "Current native financial application state for the checkout, including pending, applied, blocked or reconciliation-required owner effects.",
  "example": "example"
}
terminalRequired

True after a retained no-funds termination, or after APPLIED native effects with captured, partially refunded, refunded, canceled or expired funds. UNKNOWN or a retryable decline alone remains nonterminal.

boolean
Full definition
{
  "type": "boolean",
  "description": "True after a retained no-funds termination, or after APPLIED native effects with captured, partially refunded, refunded, canceled or expired funds. UNKNOWN or a retryable decline alone remains nonterminal.",
  "example": true
}
retryAtRequired

UTC ISO-8601 next-attempt time retained on the original operation while progress is nonterminal and not marked RECONCILIATION_REQUIRED; null for terminal or manual-reconciliation progress. This scheduling hint grants no dispatch authority.

string · date-time · null
Full definition
{
  "type": "string",
  "format": "date-time",
  "nullable": true,
  "description": "UTC ISO-8601 next-attempt time retained on the original operation while progress is nonterminal and not marked RECONCILIATION_REQUIRED; null for terminal or manual-reconciliation progress. This scheduling hint grants no dispatch authority.",
  "example": "2026-01-15T12:00:00.000Z"
}
providerRequired

Original hosted-checkout navigation and its deadline, with redirect availability derived from the current checkout progress.

allOf
Full definition
{
  "description": "Original hosted-checkout navigation and its deadline, with redirect availability derived from the current checkout progress.",
  "allOf": [
    {
      "$ref": "#/components/schemas/GuestPaymentProviderNavigationDto"
    }
  ],
  "example": {
    "redirectUrl": null,
    "expiresAt": null
  }
}
Full definition
{
  "type": "object",
  "properties": {
    "receipt": {
      "description": "Immutable first PREPARED acknowledgement for this checkout, retaining the original command, operation and accepted monetary amounts.",
      "allOf": [
        {
          "$ref": "#/components/schemas/GuestPaymentCommandReceiptDto"
        }
      ],
      "example": {
        "schema": "hallify.restaurant-payment.command-result",
        "version": 1,
        "checkoutId": "f5ef2bdc-76ae-45b6-851a-399882860529",
        "operationId": "44352441-86e0-4a70-8642-d5863bea459a",
        "action": "CREATE_CHECKOUT",
        "state": "PREPARED",
        "currency": "USD",
        "principalAmount": "12.50",
        "tipAmount": "0.00",
        "totalAmount": "12.50"
      }
    },
    "checkoutId": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the exact original checkout authorized for this disclosure.",
      "example": "f5ef2bdc-76ae-45b6-851a-399882860529"
    },
    "operationId": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the original CREATE_CHECKOUT provider operation whose current state is reported.",
      "example": "44352441-86e0-4a70-8642-d5863bea459a"
    },
    "state": {
      "type": "string",
      "enum": [
        "PREPARED",
        "DISPATCHING",
        "PENDING",
        "UNKNOWN",
        "SUCCEEDED",
        "REJECTED",
        "RECONCILIATION_REQUIRED"
      ],
      "description": "Current state of the original provider operation. Funds and native financial application progress are reported in their dedicated fields.",
      "example": "PREPARED"
    },
    "fundsState": {
      "type": "string",
      "description": "Current stored checkout funds projection, including unresolved or unknown provider evidence and admitted later financial operations.",
      "example": "1.000"
    },
    "applicationState": {
      "type": "string",
      "description": "Current native financial application state for the checkout, including pending, applied, blocked or reconciliation-required owner effects.",
      "example": "example"
    },
    "terminal": {
      "type": "boolean",
      "description": "True after a retained no-funds termination, or after APPLIED native effects with captured, partially refunded, refunded, canceled or expired funds. UNKNOWN or a retryable decline alone remains nonterminal.",
      "example": true
    },
    "retryAt": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "UTC ISO-8601 next-attempt time retained on the original operation while progress is nonterminal and not marked RECONCILIATION_REQUIRED; null for terminal or manual-reconciliation progress. This scheduling hint grants no dispatch authority.",
      "example": "2026-01-15T12:00:00.000Z"
    },
    "provider": {
      "description": "Original hosted-checkout navigation and its deadline, with redirect availability derived from the current checkout progress.",
      "allOf": [
        {
          "$ref": "#/components/schemas/GuestPaymentProviderNavigationDto"
        }
      ],
      "example": {
        "redirectUrl": null,
        "expiresAt": null
      }
    }
  },
  "description": "Current original-checkout operation, funds, native application and navigation progress together with its immutable first acknowledgement, disclosed under current exact-resource native authority.",
  "required": [
    "receipt",
    "checkoutId",
    "operationId",
    "state",
    "fundsState",
    "applicationState",
    "terminal",
    "retryAt",
    "provider"
  ],
  "example": {
    "receipt": {
      "schema": "hallify.restaurant-payment.command-result",
      "version": 1,
      "checkoutId": "f5ef2bdc-76ae-45b6-851a-399882860529",
      "operationId": "44352441-86e0-4a70-8642-d5863bea459a",
      "action": "CREATE_CHECKOUT",
      "state": "PREPARED",
      "currency": "USD",
      "principalAmount": "12.50",
      "tipAmount": "0.00",
      "totalAmount": "12.50"
    },
    "checkoutId": "f5ef2bdc-76ae-45b6-851a-399882860529",
    "operationId": "44352441-86e0-4a70-8642-d5863bea459a",
    "state": "PREPARED",
    "fundsState": "1.000",
    "applicationState": "example",
    "terminal": true,
    "retryAt": null,
    "provider": {
      "redirectUrl": null,
      "expiresAt": null
    }
  }
}
GuestPaymentCommandReceiptDto

Immutable first PREPARED acknowledgement of the permanent guest CREATE_CHECKOUT command, preserved across identical replay and original-command recovery.

schemaRequired

Discriminator identifying the versioned original payment-command result document.

string
Full definition
{
  "type": "string",
  "enum": [
    "hallify.restaurant-payment.command-result"
  ],
  "description": "Discriminator identifying the versioned original payment-command result document.",
  "example": "hallify.restaurant-payment.command-result"
}
versionRequired

Command-result schema version retained by this acknowledgement.

integer
Full definition
{
  "type": "integer",
  "enum": [
    1
  ],
  "description": "Command-result schema version retained by this acknowledgement.",
  "example": 1
}
checkoutIdRequired

UUID of the original checkout allocated once for this permanent command.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "description": "UUID of the original checkout allocated once for this permanent command.",
  "example": "f5ef2bdc-76ae-45b6-851a-399882860529"
}
operationIdRequired

UUID of the original CREATE_CHECKOUT provider operation; replay and recovery preserve this operation identity.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "description": "UUID of the original CREATE_CHECKOUT provider operation; replay and recovery preserve this operation identity.",
  "example": "44352441-86e0-4a70-8642-d5863bea459a"
}
actionRequired

Original accepted command action; this guest boundary acknowledges CREATE_CHECKOUT.

string
Full definition
{
  "type": "string",
  "enum": [
    "CREATE_CHECKOUT"
  ],
  "description": "Original accepted command action; this guest boundary acknowledges CREATE_CHECKOUT.",
  "example": "CREATE_CHECKOUT"
}
stateRequired

State at the first retained acknowledgement, always PREPARED. Current operation, funds and native application states are returned by the checkout progress operation.

string
Full definition
{
  "type": "string",
  "enum": [
    "PREPARED"
  ],
  "description": "State at the first retained acknowledgement, always PREPARED. Current operation, funds and native application states are returned by the checkout progress operation.",
  "example": "PREPARED"
}
currencyRequired

Currency of the original frozen principal, tip and total amounts.

string
Full definition
{
  "type": "string",
  "enum": [
    "USD",
    "GEL"
  ],
  "description": "Currency of the original frozen principal, tip and total amounts.",
  "example": "USD"
}
principalAmountRequired

Original frozen principal before the separately accepted tip, as a two-decimal string in receipt currency.

string
Full definition
{
  "type": "string",
  "example": "12.50",
  "description": "Original frozen principal before the separately accepted tip, as a two-decimal string in receipt currency."
}
tipAmountRequired

Original frozen tip accepted with the command, as a nonnegative two-decimal string in receipt currency.

string
Full definition
{
  "type": "string",
  "example": "0.00",
  "description": "Original frozen tip accepted with the command, as a nonnegative two-decimal string in receipt currency."
}
totalAmountRequired

Original sum of frozen principal and accepted tip, as a two-decimal string in receipt currency.

string
Full definition
{
  "type": "string",
  "example": "12.50",
  "description": "Original sum of frozen principal and accepted tip, as a two-decimal string in receipt currency."
}
Full definition
{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "hallify.restaurant-payment.command-result"
      ],
      "description": "Discriminator identifying the versioned original payment-command result document.",
      "example": "hallify.restaurant-payment.command-result"
    },
    "version": {
      "type": "integer",
      "enum": [
        1
      ],
      "description": "Command-result schema version retained by this acknowledgement.",
      "example": 1
    },
    "checkoutId": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the original checkout allocated once for this permanent command.",
      "example": "f5ef2bdc-76ae-45b6-851a-399882860529"
    },
    "operationId": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the original CREATE_CHECKOUT provider operation; replay and recovery preserve this operation identity.",
      "example": "44352441-86e0-4a70-8642-d5863bea459a"
    },
    "action": {
      "type": "string",
      "enum": [
        "CREATE_CHECKOUT"
      ],
      "description": "Original accepted command action; this guest boundary acknowledges CREATE_CHECKOUT.",
      "example": "CREATE_CHECKOUT"
    },
    "state": {
      "type": "string",
      "enum": [
        "PREPARED"
      ],
      "description": "State at the first retained acknowledgement, always PREPARED. Current operation, funds and native application states are returned by the checkout progress operation.",
      "example": "PREPARED"
    },
    "currency": {
      "type": "string",
      "enum": [
        "USD",
        "GEL"
      ],
      "description": "Currency of the original frozen principal, tip and total amounts.",
      "example": "USD"
    },
    "principalAmount": {
      "type": "string",
      "example": "12.50",
      "description": "Original frozen principal before the separately accepted tip, as a two-decimal string in receipt currency."
    },
    "tipAmount": {
      "type": "string",
      "example": "0.00",
      "description": "Original frozen tip accepted with the command, as a nonnegative two-decimal string in receipt currency."
    },
    "totalAmount": {
      "type": "string",
      "example": "12.50",
      "description": "Original sum of frozen principal and accepted tip, as a two-decimal string in receipt currency."
    }
  },
  "description": "Immutable first PREPARED acknowledgement of the permanent guest CREATE_CHECKOUT command, preserved across identical replay and original-command recovery.",
  "required": [
    "schema",
    "version",
    "checkoutId",
    "operationId",
    "action",
    "state",
    "currency",
    "principalAmount",
    "tipAmount",
    "totalAmount"
  ],
  "example": {
    "schema": "hallify.restaurant-payment.command-result",
    "version": 1,
    "checkoutId": "f5ef2bdc-76ae-45b6-851a-399882860529",
    "operationId": "44352441-86e0-4a70-8642-d5863bea459a",
    "action": "CREATE_CHECKOUT",
    "state": "PREPARED",
    "currency": "USD",
    "principalAmount": "12.50",
    "tipAmount": "0.00",
    "totalAmount": "12.50"
  }
}
GuestPaymentProviderNavigationDto

Navigation to the original hosted provider checkout when currently allowed, with the retained provider or checkout deadline; navigation alone establishes no financial result.

redirectUrlRequired

Original provider redirect URL when a dispatch exists, checkout progress permits navigation and the deadline has not passed; otherwise null. Returning from this URL establishes no payment result.

string · null
Full definition
{
  "type": "string",
  "nullable": true,
  "description": "Original provider redirect URL when a dispatch exists, checkout progress permits navigation and the deadline has not passed; otherwise null. Returning from this URL establishes no payment result.",
  "example": "https://example.test/resource"
}
expiresAtRequired

UTC ISO-8601 navigation deadline, using the retained provider expiry or the original checkout deadline as fallback.

string · date-time · null
Full definition
{
  "type": "string",
  "format": "date-time",
  "nullable": true,
  "description": "UTC ISO-8601 navigation deadline, using the retained provider expiry or the original checkout deadline as fallback.",
  "example": "2026-12-31T18:00:00.000Z"
}
Full definition
{
  "type": "object",
  "properties": {
    "redirectUrl": {
      "type": "string",
      "nullable": true,
      "description": "Original provider redirect URL when a dispatch exists, checkout progress permits navigation and the deadline has not passed; otherwise null. Returning from this URL establishes no payment result.",
      "example": "https://example.test/resource"
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "UTC ISO-8601 navigation deadline, using the retained provider expiry or the original checkout deadline as fallback.",
      "example": "2026-12-31T18:00:00.000Z"
    }
  },
  "description": "Navigation to the original hosted provider checkout when currently allowed, with the retained provider or checkout deadline; navigation alone establishes no financial result.",
  "required": [
    "redirectUrl",
    "expiresAt"
  ],
  "example": {
    "redirectUrl": null,
    "expiresAt": null
  }
}
TranslatedErrorDto

Stable error envelope emitted by the global HTTP exception boundary. Domain-specific machine data, when present, is nested under details.

statusCodeRequired

HTTP status code repeated from the response.

integer
Full definition
{
  "type": "integer",
  "description": "HTTP status code repeated from the response.",
  "example": 400
}
errorRequired

Translation key for the HTTP category, such as errors:http.conflict. The specific cause is identified by code and translationKey.

string
Full definition
{
  "type": "string",
  "description": "Translation key for the HTTP category, such as errors:http.conflict. The specific cause is identified by code and translationKey.",
  "example": "errors.request.invalid"
}
codeRequired

Stable machine-readable domain code, or an HTTP_* fallback when no domain code is provided. Branch on this field and the HTTP status; localized wording never controls retries or business decisions.

string
Full definition
{
  "type": "string",
  "example": "HTTP_BAD_REQUEST",
  "description": "Stable machine-readable domain code, or an HTTP_* fallback when no domain code is provided. Branch on this field and the HTTP status; localized wording never controls retries or business decisions."
}
messageRequired

Translation key, identical to translationKey. The API does not return localized display text. Resolve the key and translationValues in the consuming application.

string
Full definition
{
  "type": "string",
  "example": "errors:http.badRequest",
  "description": "Translation key, identical to translationKey. The API does not return localized display text. Resolve the key and translationValues in the consuming application."
}
translationKeyRequired

Canonical translation key, identical to message. Status-specific errors:http.* keys cover unspecified failures. Public keys and EN/RU explanations are listed in Developers; unknown keys require a localized client fallback.

string
Full definition
{
  "type": "string",
  "example": "errors:http.badRequest",
  "description": "Canonical translation key, identical to message. Status-specific errors:http.* keys cover unspecified failures. Public keys and EN/RU explanations are listed in Developers; unknown keys require a localized client fallback."
}
translationValuesOptional

Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.

object
Full definition
{
  "type": "object",
  "additionalProperties": {
    "oneOf": [
      {
        "type": "string",
        "example": "example"
      },
      {
        "type": "number",
        "example": 0
      },
      {
        "type": "boolean",
        "example": true
      }
    ],
    "example": "example"
  },
  "description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.",
  "example": {
    "exampleKey": "example"
  }
}
validationErrorsOptional

Field validation failures with translation keys and stable validator codes. Submitted values and raw validator text are not included.

array
Full definition
{
  "description": "Field validation failures with translation keys and stable validator codes. Submitted values and raw validator text are not included.",
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/ValidationErrorDto"
  },
  "example": [
    {
      "field": "email",
      "translationKey": "validation:isEmail",
      "code": "isEmail",
      "message": "validation:isEmail"
    }
  ]
}
detailsOptional

Optional domain-specific blocker or validation details

oneOf
Full definition
{
  "description": "Optional domain-specific blocker or validation details",
  "oneOf": [
    {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/JsonValue"
      },
      "example": [
        "example"
      ]
    },
    {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/components/schemas/JsonValue"
      },
      "example": {
        "exampleKey": "example"
      }
    }
  ],
  "example": [
    "example"
  ]
}
Full definition
{
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "integer",
      "description": "HTTP status code repeated from the response.",
      "example": 400
    },
    "error": {
      "type": "string",
      "description": "Translation key for the HTTP category, such as errors:http.conflict. The specific cause is identified by code and translationKey.",
      "example": "errors.request.invalid"
    },
    "code": {
      "type": "string",
      "example": "HTTP_BAD_REQUEST",
      "description": "Stable machine-readable domain code, or an HTTP_* fallback when no domain code is provided. Branch on this field and the HTTP status; localized wording never controls retries or business decisions."
    },
    "message": {
      "type": "string",
      "example": "errors:http.badRequest",
      "description": "Translation key, identical to translationKey. The API does not return localized display text. Resolve the key and translationValues in the consuming application."
    },
    "translationKey": {
      "type": "string",
      "example": "errors:http.badRequest",
      "description": "Canonical translation key, identical to message. Status-specific errors:http.* keys cover unspecified failures. Public keys and EN/RU explanations are listed in Developers; unknown keys require a localized client fallback."
    },
    "translationValues": {
      "type": "object",
      "additionalProperties": {
        "oneOf": [
          {
            "type": "string",
            "example": "example"
          },
          {
            "type": "number",
            "example": 0
          },
          {
            "type": "boolean",
            "example": true
          }
        ],
        "example": "example"
      },
      "description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.",
      "example": {
        "exampleKey": "example"
      }
    },
    "validationErrors": {
      "description": "Field validation failures with translation keys and stable validator codes. Submitted values and raw validator text are not included.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ValidationErrorDto"
      },
      "example": [
        {
          "field": "email",
          "translationKey": "validation:isEmail",
          "code": "isEmail",
          "message": "validation:isEmail"
        }
      ]
    },
    "details": {
      "description": "Optional domain-specific blocker or validation details",
      "oneOf": [
        {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/JsonValue"
          },
          "example": [
            "example"
          ]
        },
        {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/components/schemas/JsonValue"
          },
          "example": {
            "exampleKey": "example"
          }
        }
      ],
      "example": [
        "example"
      ]
    }
  },
  "required": [
    "statusCode",
    "error",
    "code",
    "message",
    "translationKey"
  ],
  "description": "Stable error envelope emitted by the global HTTP exception boundary. Domain-specific machine data, when present, is nested under details.",
  "example": {
    "statusCode": 400,
    "error": "errors:http.badRequest",
    "code": "HTTP_BAD_REQUEST",
    "message": "errors:http.badRequest",
    "translationKey": "errors:http.badRequest"
  }
}
ValidationErrorDto

Field validation failure with a field path, stable validator code and a translation key. Human-readable text belongs to the consuming application.

fieldRequired

Public field path. Nested properties and array indices are separated by dots.

string
Full definition
{
  "type": "string",
  "example": "email",
  "description": "Public field path. Nested properties and array indices are separated by dots."
}
translationKeyRequired

Translation key for this validator, identical to message. Resolve it using a client dictionary; see the public Developers error catalog.

string
Full definition
{
  "type": "string",
  "example": "validation:isEmail",
  "description": "Translation key for this validator, identical to message. Resolve it using a client dictionary; see the public Developers error catalog."
}
codeRequired

Stable validator identifier for this field failure. Custom validators may define additional identifiers.

string
Full definition
{
  "type": "string",
  "example": "isEmail",
  "description": "Stable validator identifier for this field failure. Custom validators may define additional identifiers."
}
messageRequired

Translation key describing this field validation failure, identical to translationKey. Submitted values and validator prose are not included.

string
Full definition
{
  "type": "string",
  "example": "validation:isEmail",
  "description": "Translation key describing this field validation failure, identical to translationKey. Submitted values and validator prose are not included."
}
translationValuesOptional

Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.

object
Full definition
{
  "type": "object",
  "additionalProperties": {
    "oneOf": [
      {
        "type": "string",
        "example": "example"
      },
      {
        "type": "number",
        "example": 0
      },
      {
        "type": "boolean",
        "example": true
      }
    ],
    "example": "example"
  },
  "description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.",
  "example": {
    "exampleKey": "example"
  }
}
Full definition
{
  "type": "object",
  "properties": {
    "field": {
      "type": "string",
      "example": "email",
      "description": "Public field path. Nested properties and array indices are separated by dots."
    },
    "translationKey": {
      "type": "string",
      "example": "validation:isEmail",
      "description": "Translation key for this validator, identical to message. Resolve it using a client dictionary; see the public Developers error catalog."
    },
    "code": {
      "type": "string",
      "example": "isEmail",
      "description": "Stable validator identifier for this field failure. Custom validators may define additional identifiers."
    },
    "message": {
      "type": "string",
      "example": "validation:isEmail",
      "description": "Translation key describing this field validation failure, identical to translationKey. Submitted values and validator prose are not included."
    },
    "translationValues": {
      "type": "object",
      "additionalProperties": {
        "oneOf": [
          {
            "type": "string",
            "example": "example"
          },
          {
            "type": "number",
            "example": 0
          },
          {
            "type": "boolean",
            "example": true
          }
        ],
        "example": "example"
      },
      "description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.",
      "example": {
        "exampleKey": "example"
      }
    }
  },
  "required": [
    "field",
    "translationKey",
    "code",
    "message"
  ],
  "description": "Field validation failure with a field path, stable validator code and a translation key. Human-readable text belongs to the consuming application.",
  "example": {
    "field": "email",
    "translationKey": "validation:isEmail",
    "code": "isEmail",
    "message": "validation:isEmail"
  }
}
JsonValue

Recursively JSON-safe value used only where the owning contract intentionally allows free-form structured data.

Full definition
{
  "oneOf": [
    {
      "type": "string",
      "nullable": true,
      "example": "example"
    },
    {
      "type": "number",
      "example": 0
    },
    {
      "type": "boolean",
      "example": true
    },
    {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/JsonValue"
      },
      "example": [
        "example"
      ]
    },
    {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/components/schemas/JsonValue"
      },
      "example": {
        "exampleKey": "example"
      }
    }
  ],
  "description": "Recursively JSON-safe value used only where the owning contract intentionally allows free-form structured data.",
  "example": "example"
}

Hallify uses essential cookies and optional analytics.

Essential cookies keep sign-in, locale, and theme preferences working. Analytics is off until you choose to allow it.