Read the proposed agreement after real guest verification

Authentication

x-hallify-widget-context: <HALLIFY_STOREFRONT_WIDGET_CONTEXT>

Short-lived server-authenticated widget presentation proof. It binds the configured frame origin to the exact verified parent binding and connection authority. Widget new demand requires this proof; existing native capabilities remain separate and retain their original authority and deadlines.

Connection guide

Parameters

publicHandlePath · Required: Published native reservation channel handle.
string
Full definition
{ "type": "string", "example": "example" }
changeIdPath · Required: Exact agreement change bound to the contact challenge.
string · uuid
Full definition
{ "type": "string", "format": "uuid", "example": "9b6163a8-afea-4877-818b-8e2ae28a2845" }
idempotency-keyHeader · Required: Required idempotency key, up to 128 characters
string
Full definition
{ "type": "string", "minLength": 1, "maxLength": 128, "example": "example" }
originHeader · Optional: Actual browser request Origin used for current presentation authorization. New demand and Storefront-bound continuations require it. Canonical Hallify browser requests use the origin configured by HALLIFY_PUBLIC_APP_URL. This header provides request context and does not authenticate a caller or replace the applicable guest credential.
string · uri
Full definition
{ "type": "string", "format": "uri", "maxLength": 2048, "example": "https://example.test/resource" }
x-hallify-connection-idHeader · Optional: Optional nonsecret connection locator for initial public channel resolution. It never grants authority or replaces an issued grant snapshot.
string · uuid
Full definition
{ "type": "string", "format": "uuid", "minLength": 36, "maxLength": 36, "example": "9b6163a8-afea-4877-818b-8e2ae28a2845" }

Request body

Required

Original short-lived contact challenge capability and actual verification code delivered to the guest.

application/json

ReservationAgreementVerifyDto

Full definition

{
  "$ref": "#/components/schemas/ReservationAgreementVerifyDto"
}

Responses

200Original verified proposal and acceptance capability with its fixed deadline.

ReservationAgreementVerifiedResultDto

Full definition

{
  "$ref": "#/components/schemas/ReservationAgreementVerifiedResultDto"
}

Example response · 200 · application/json

{
  "agreement": {
    "id": "7333b91d-1456-424d-8cf4-d12591cce3e7",
    "action": "CHANGE",
    "state": "PENDING",
    "revision": 1,
    "planHash": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
    "expiresAt": "2026-12-31T18:00:00.000Z",
    "scheduledAt": "2026-01-15T12:00:00.000Z",
    "endsAt": "2026-12-31T18:00:00.000Z",
    "partySize": 1,
    "servicePeriodId": "4846c409-f4df-40f6-81cc-1d7157a5c646",
    "offer": {
      "required": true,
      "terms": null,
      "termsHash": null
    },
    "activatedAgreementVersion": null,
    "activatedReservationRevision": null
  },
  "capability": "example",
  "expiresAt": "2026-12-31T18:00:00.000Z"
}

402Commercial coverage is required for new demand, or this operation has no original commercial admission evidence. Existing authorized reads and financial recovery remain available.

TranslatedErrorDto

Full definition

{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}

Example response · 402 · application/json

{
  "statusCode": 402,
  "error": "errors:http.failure",
  "code": "HTTP_402",
  "message": "errors:http.failure",
  "translationKey": "errors:http.failure"
}

409Idempotency key is already in progress or was reused with a different payload

IdempotencyConflictError

Full definition

{
  "$ref": "#/components/schemas/IdempotencyConflictError"
}

Example response · 409 · application/json

{
  "statusCode": 409,
  "error": "errors:http.conflict",
  "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
  "message": "errors:idempotency.inProgress",
  "translationKey": "errors:idempotency.inProgress"
}

503Authoritative commercial state is unavailable or cannot be read within its bounded source contract. Retry the same operation after recovery.

TranslatedErrorDto

Full definition

{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}

Example response · 503 · application/json

{
  "statusCode": 503,
  "error": "errors:http.serviceUnavailable",
  "code": "HTTP_SERVICE_UNAVAILABLE",
  "message": "errors:http.serviceUnavailable",
  "translationKey": "errors:http.serviceUnavailable"
}

Schemas

ReservationAgreementVerifyDto

Verification-code confirmation for the original reservation agreement challenge, bound to its proposal, request Origin and fingerprint.

capabilityRequired: Exact short-lived challenge capability bound to this proposal, Origin and request fingerprint.
string
Full definition
{ "type": "string", "maxLength": 4096, "description": "Exact short-lived challenge capability bound to this proposal, Origin and request fingerprint.", "example": "example" }
codeRequired: Actual verification code sent to the guest contact.
string
Full definition
{ "type": "string", "minLength": 4, "maxLength": 12, "description": "Actual verification code sent to the guest contact.", "example": "EXAMPLE" }

Full definition

{
  "type": "object",
  "properties": {
    "capability": {
      "type": "string",
      "maxLength": 4096,
      "description": "Exact short-lived challenge capability bound to this proposal, Origin and request fingerprint.",
      "example": "example"
    },
    "code": {
      "type": "string",
      "minLength": 4,
      "maxLength": 12,
      "description": "Actual verification code sent to the guest contact.",
      "example": "EXAMPLE"
    }
  },
  "required": [
    "capability",
    "code"
  ],
  "description": "Verification-code confirmation for the original reservation agreement challenge, bound to its proposal, request Origin and fingerprint.",
  "example": {
    "capability": "example",
    "code": "EXAMPLE"
  }
}

ReservationAgreementVerifiedResultDto

Original verified proposal and short-lived capability for explicitly accepting its exact digest.

agreementRequired: Current authorized agreement change with its exact proposed slot and guarantee offer.
object
Full definition
{ "type": "object", "description": "Current authorized agreement change with its exact proposed slot and guarantee offer.", "additionalProperties": false, "required": [ "id", "action", "state", "revision", "planHash", "expiresAt", "scheduledAt", "endsAt", "partySize", "servicePeriodId", "offer", "activatedAgreementVersion", "activatedReservationRevision" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Native agreement change UUID.", "example": "7333b91d-1456-424d-8cf4-d12591cce3e7" }, "action": { "type": "string", "enum": [ "CHANGE", "RESTORE" ], "description": "Explicit proposed native action.", "example": "CHANGE" }, "state": { "type": "string", "enum": [ "PENDING", "ACCEPTED", "ACTIVATED", "EXPIRED", "SUPERSEDED" ], "description": "Current native continuation state.", "example": "PENDING" }, "revision": { "type": "integer", "minimum": 1, "description": "Current native proposal revision.", "example": 1 }, "planHash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Exact frozen slot and terms digest.", "example": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Fixed activation deadline.", "example": "2026-12-31T18:00:00.000Z" }, "scheduledAt": { "type": "string", "format": "date-time", "description": "Exact proposed scheduled instant.", "example": "2026-01-15T12:00:00.000Z" }, "endsAt": { "type": "string", "format": "date-time", "description": "Exact proposed visit end instant.", "example": "2026-12-31T18:00:00.000Z" }, "partySize": { "type": "integer", "minimum": 1, "maximum": 99, "description": "Exact proposed guest count.", "example": 1 }, "servicePeriodId": { "type": "string", "format": "uuid", "description": "Proposed native service period.", "example": "4846c409-f4df-40f6-81cc-1d7157a5c646" }, "offer": { "type": "object", "description": "Server-computed guarantee proposal with its terms and digest. NONE or a party below the configured threshold requires no guarantee.", "additionalProperties": false, "required": [ "required", "terms", "termsHash" ], "properties": { "required": { "type": "boolean", "description": "Whether this exact slot and party require a guarantee.", "example": true }, "terms": { "type": "object", "description": "Exact accepted terms, or null when no guarantee applies.", "additionalProperties": false, "required": [ "schema", "version", "venueId", "publicChannelId", "servicePeriodId", "servicePeriodRevision", "kind", "amountBasis", "unitAmount", "totalAmount", "currency", "currencyMinorUnit", "partySize", "scheduledAt", "dueAt", "freeCancellationAt", "noShowAfter", "forfeitOnLateCancellation", "forfeitOnNoShow", "termsVersion", "privacyVersion" ], "properties": { "schema": { "type": "string", "enum": [ "hallify.reservation-guarantee.terms" ], "description": "Canonical native terms schema.", "example": "hallify.reservation-guarantee.terms" }, "version": { "type": "integer", "enum": [ 1 ], "description": "Canonical native terms version.", "example": 1 }, "venueId": { "type": "string", "format": "uuid", "description": "Native venue UUID.", "example": "0604de3a-da74-4ad5-89f6-2dfe000d5391" }, "publicChannelId": { "type": "string", "format": "uuid", "description": "Native reservation channel UUID.", "example": "9bee613d-3322-4a03-8b9f-8a6259984eee" }, "servicePeriodId": { "type": "string", "format": "uuid", "description": "Selected native service-period UUID.", "example": "4846c409-f4df-40f6-81cc-1d7157a5c646" }, "servicePeriodRevision": { "type": "integer", "minimum": 1, "description": "Accepted native service-period revision.", "example": 1 }, "kind": { "type": "string", "enum": [ "DEPOSIT", "CARD_HOLD", "PREPAID" ], "description": "Original accepted guarantee kind.", "example": "DEPOSIT" }, "amountBasis": { "type": "string", "enum": [ "FIXED", "PER_GUEST" ], "description": "Original amount calculation basis.", "example": "FIXED" }, "unitAmount": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,9})\\.[0-9]{2}$", "description": "Exact two-decimal amount per booking or guest.", "example": "1.00" }, "totalAmount": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,9})\\.[0-9]{2}$", "description": "Exact two-decimal accepted total principal, with no tip.", "example": "1.00" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Original native currency; no conversion is performed.", "example": "GEL" }, "currencyMinorUnit": { "type": "integer", "enum": [ 2 ], "description": "Native monetary scale.", "example": 2 }, "partySize": { "type": "integer", "minimum": 1, "maximum": 99, "description": "Exact accepted party size.", "example": 1 }, "scheduledAt": { "type": "string", "format": "date-time", "description": "Exact scheduled UTC slot instant.", "example": "2026-01-15T12:00:00.000Z" }, "dueAt": { "type": "string", "format": "date-time", "description": "Exact payment deadline before conversion and collection.", "example": "2026-12-31T18:00:00.000Z" }, "freeCancellationAt": { "type": "string", "format": "date-time", "description": "Exact free-cancellation cutoff.", "example": "2026-01-15T12:00:00.000Z" }, "noShowAfter": { "type": "string", "format": "date-time", "description": "Earliest no-show forfeiture instant under the accepted grace rule.", "example": "2026-01-15T12:00:00.000Z" }, "forfeitOnLateCancellation": { "type": "boolean", "description": "Accepted permission for explicit staff late-cancellation forfeiture.", "example": true }, "forfeitOnNoShow": { "type": "boolean", "description": "Accepted permission for explicit staff no-show forfeiture; no automatic card debit.", "example": true }, "termsVersion": { "type": "string", "description": "Accepted public terms version.", "example": "example" }, "privacyVersion": { "type": "string", "description": "Accepted privacy notice version.", "example": "example" } }, "nullable": true, "example": { "schema": "hallify.reservation-guarantee.terms", "version": 1, "venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391", "publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee", "servicePeriodId": "4846c409-f4df-40f6-81cc-1d7157a5c646", "servicePeriodRevision": 1, "kind": "DEPOSIT", "amountBasis": "FIXED", "unitAmount": "1.00", "totalAmount": "1.00", "currency": "GEL", "currencyMinorUnit": 2, "partySize": 1, "scheduledAt": "2026-01-15T12:00:00.000Z", "dueAt": "2026-12-31T18:00:00.000Z", "freeCancellationAt": "2026-01-15T12:00:00.000Z", "noShowAfter": "2026-01-15T12:00:00.000Z", "forfeitOnLateCancellation": true, "forfeitOnNoShow": true, "termsVersion": "example", "privacyVersion": "example" } }, "termsHash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "nullable": true, "description": "Canonical accepted terms digest, or null when no guarantee applies.", "example": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef" } }, "example": { "required": true, "terms": null, "termsHash": null } }, "activatedAgreementVersion": { "type": "integer", "minimum": 1, "nullable": true, "description": "Actual activated agreement version, or null before activation.", "example": 1 }, "activatedReservationRevision": { "type": "integer", "minimum": 1, "nullable": true, "description": "Actual native revision recorded by activation, or null.", "example": 1 } }, "example": { "id": "7333b91d-1456-424d-8cf4-d12591cce3e7", "action": "CHANGE", "state": "PENDING", "revision": 1, "planHash": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef", "expiresAt": "2026-12-31T18:00:00.000Z", "scheduledAt": "2026-01-15T12:00:00.000Z", "endsAt": "2026-12-31T18:00:00.000Z", "partySize": 1, "servicePeriodId": "4846c409-f4df-40f6-81cc-1d7157a5c646", "offer": { "required": true, "terms": null, "termsHash": null }, "activatedAgreementVersion": null, "activatedReservationRevision": null } }
capabilityRequired: Sensitive capability bound to the actually verified existing guest and exact frozen proposal.
string
Full definition
{ "type": "string", "maxLength": 4096, "description": "Sensitive capability bound to the actually verified existing guest and exact frozen proposal.", "example": "example" }
expiresAtRequired: Original explicit acceptance deadline.
string · date-time
Full definition
{ "type": "string", "format": "date-time", "description": "Original explicit acceptance deadline.", "example": "2026-12-31T18:00:00.000Z" }

Full definition

{
  "type": "object",
  "description": "Original verified proposal and short-lived capability for explicitly accepting its exact digest.",
  "additionalProperties": false,
  "required": [
    "agreement",
    "capability",
    "expiresAt"
  ],
  "properties": {
    "agreement": {
      "type": "object",
      "description": "Current authorized agreement change with its exact proposed slot and guarantee offer.",
      "additionalProperties": false,
      "required": [
        "id",
        "action",
        "state",
        "revision",
        "planHash",
        "expiresAt",
        "scheduledAt",
        "endsAt",
        "partySize",
        "servicePeriodId",
        "offer",
        "activatedAgreementVersion",
        "activatedReservationRevision"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Native agreement change UUID.",
          "example": "7333b91d-1456-424d-8cf4-d12591cce3e7"
        },
        "action": {
          "type": "string",
          "enum": [
            "CHANGE",
            "RESTORE"
          ],
          "description": "Explicit proposed native action.",
          "example": "CHANGE"
        },
        "state": {
          "type": "string",
          "enum": [
            "PENDING",
            "ACCEPTED",
            "ACTIVATED",
            "EXPIRED",
            "SUPERSEDED"
          ],
          "description": "Current native continuation state.",
          "example": "PENDING"
        },
        "revision": {
          "type": "integer",
          "minimum": 1,
          "description": "Current native proposal revision.",
          "example": 1
        },
        "planHash": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$",
          "description": "Exact frozen slot and terms digest.",
          "example": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
        },
        "expiresAt": {
          "type": "string",
          "format": "date-time",
          "description": "Fixed activation deadline.",
          "example": "2026-12-31T18:00:00.000Z"
        },
        "scheduledAt": {
          "type": "string",
          "format": "date-time",
          "description": "Exact proposed scheduled instant.",
          "example": "2026-01-15T12:00:00.000Z"
        },
        "endsAt": {
          "type": "string",
          "format": "date-time",
          "description": "Exact proposed visit end instant.",
          "example": "2026-12-31T18:00:00.000Z"
        },
        "partySize": {
          "type": "integer",
          "minimum": 1,
          "maximum": 99,
          "description": "Exact proposed guest count.",
          "example": 1
        },
        "servicePeriodId": {
          "type": "string",
          "format": "uuid",
          "description": "Proposed native service period.",
          "example": "4846c409-f4df-40f6-81cc-1d7157a5c646"
        },
        "offer": {
          "type": "object",
          "description": "Server-computed guarantee proposal with its terms and digest. NONE or a party below the configured threshold requires no guarantee.",
          "additionalProperties": false,
          "required": [
            "required",
            "terms",
            "termsHash"
          ],
          "properties": {
            "required": {
              "type": "boolean",
              "description": "Whether this exact slot and party require a guarantee.",
              "example": true
            },
            "terms": {
              "type": "object",
              "description": "Exact accepted terms, or null when no guarantee applies.",
              "additionalProperties": false,
              "required": [
                "schema",
                "version",
                "venueId",
                "publicChannelId",
                "servicePeriodId",
                "servicePeriodRevision",
                "kind",
                "amountBasis",
                "unitAmount",
                "totalAmount",
                "currency",
                "currencyMinorUnit",
                "partySize",
                "scheduledAt",
                "dueAt",
                "freeCancellationAt",
                "noShowAfter",
                "forfeitOnLateCancellation",
                "forfeitOnNoShow",
                "termsVersion",
                "privacyVersion"
              ],
              "properties": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "hallify.reservation-guarantee.terms"
                  ],
                  "description": "Canonical native terms schema.",
                  "example": "hallify.reservation-guarantee.terms"
                },
                "version": {
                  "type": "integer",
                  "enum": [
                    1
                  ],
                  "description": "Canonical native terms version.",
                  "example": 1
                },
                "venueId": {
                  "type": "string",
                  "format": "uuid",
                  "description": "Native venue UUID.",
                  "example": "0604de3a-da74-4ad5-89f6-2dfe000d5391"
                },
                "publicChannelId": {
                  "type": "string",
                  "format": "uuid",
                  "description": "Native reservation channel UUID.",
                  "example": "9bee613d-3322-4a03-8b9f-8a6259984eee"
                },
                "servicePeriodId": {
                  "type": "string",
                  "format": "uuid",
                  "description": "Selected native service-period UUID.",
                  "example": "4846c409-f4df-40f6-81cc-1d7157a5c646"
                },
                "servicePeriodRevision": {
                  "type": "integer",
                  "minimum": 1,
                  "description": "Accepted native service-period revision.",
                  "example": 1
                },
                "kind": {
                  "type": "string",
                  "enum": [
                    "DEPOSIT",
                    "CARD_HOLD",
                    "PREPAID"
                  ],
                  "description": "Original accepted guarantee kind.",
                  "example": "DEPOSIT"
                },
                "amountBasis": {
                  "type": "string",
                  "enum": [
                    "FIXED",
                    "PER_GUEST"
                  ],
                  "description": "Original amount calculation basis.",
                  "example": "FIXED"
                },
                "unitAmount": {
                  "type": "string",
                  "pattern": "^(0|[1-9][0-9]{0,9})\\.[0-9]{2}$",
                  "description": "Exact two-decimal amount per booking or guest.",
                  "example": "1.00"
                },
                "totalAmount": {
                  "type": "string",
                  "pattern": "^(0|[1-9][0-9]{0,9})\\.[0-9]{2}$",
                  "description": "Exact two-decimal accepted total principal, with no tip.",
                  "example": "1.00"
                },
                "currency": {
                  "type": "string",
                  "pattern": "^[A-Z]{3}$",
                  "description": "Original native currency; no conversion is performed.",
                  "example": "GEL"
                },
                "currencyMinorUnit": {
                  "type": "integer",
                  "enum": [
                    2
                  ],
                  "description": "Native monetary scale.",
                  "example": 2
                },
                "partySize": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 99,
                  "description": "Exact accepted party size.",
                  "example": 1
                },
                "scheduledAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Exact scheduled UTC slot instant.",
                  "example": "2026-01-15T12:00:00.000Z"
                },
                "dueAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Exact payment deadline before conversion and collection.",
                  "example": "2026-12-31T18:00:00.000Z"
                },
                "freeCancellationAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Exact free-cancellation cutoff.",
                  "example": "2026-01-15T12:00:00.000Z"
                },
                "noShowAfter": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Earliest no-show forfeiture instant under the accepted grace rule.",
                  "example": "2026-01-15T12:00:00.000Z"
                },
                "forfeitOnLateCancellation": {
                  "type": "boolean",
                  "description": "Accepted permission for explicit staff late-cancellation forfeiture.",
                  "example": true
                },
                "forfeitOnNoShow": {
                  "type": "boolean",
                  "description": "Accepted permission for explicit staff no-show forfeiture; no automatic card debit.",
                  "example": true
                },
                "termsVersion": {
                  "type": "string",
                  "description": "Accepted public terms version.",
                  "example": "example"
                },
                "privacyVersion": {
                  "type": "string",
                  "description": "Accepted privacy notice version.",
                  "example": "example"
                }
              },
              "nullable": true,
              "example": {
                "schema": "hallify.reservation-guarantee.terms",
                "version": 1,
                "venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
                "publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
                "servicePeriodId": "4846c409-f4df-40f6-81cc-1d7157a5c646",
                "servicePeriodRevision": 1,
                "kind": "DEPOSIT",
                "amountBasis": "FIXED",
                "unitAmount": "1.00",
                "totalAmount": "1.00",
                "currency": "GEL",
                "currencyMinorUnit": 2,
                "partySize": 1,
                "scheduledAt": "2026-01-15T12:00:00.000Z",
                "dueAt": "2026-12-31T18:00:00.000Z",
                "freeCancellationAt": "2026-01-15T12:00:00.000Z",
                "noShowAfter": "2026-01-15T12:00:00.000Z",
                "forfeitOnLateCancellation": true,
                "forfeitOnNoShow": true,
                "termsVersion": "example",
                "privacyVersion": "example"
              }
            },
            "termsHash": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}$",
              "nullable": true,
              "description": "Canonical accepted terms digest, or null when no guarantee applies.",
              "example": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
            }
          },
          "example": {
            "required": true,
            "terms": null,
            "termsHash": null
          }
        },
        "activatedAgreementVersion": {
          "type": "integer",
          "minimum": 1,
          "nullable": true,
          "description": "Actual activated agreement version, or null before activation.",
          "example": 1
        },
        "activatedReservationRevision": {
          "type": "integer",
          "minimum": 1,
          "nullable": true,
          "description": "Actual native revision recorded by activation, or null.",
          "example": 1
        }
      },
      "example": {
        "id": "7333b91d-1456-424d-8cf4-d12591cce3e7",
        "action": "CHANGE",
        "state": "PENDING",
        "revision": 1,
        "planHash": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
        "expiresAt": "2026-12-31T18:00:00.000Z",
        "scheduledAt": "2026-01-15T12:00:00.000Z",
        "endsAt": "2026-12-31T18:00:00.000Z",
        "partySize": 1,
        "servicePeriodId": "4846c409-f4df-40f6-81cc-1d7157a5c646",
        "offer": {
          "required": true,
          "terms": null,
          "termsHash": null
        },
        "activatedAgreementVersion": null,
        "activatedReservationRevision": null
      }
    },
    "capability": {
      "type": "string",
      "maxLength": 4096,
      "description": "Sensitive capability bound to the actually verified existing guest and exact frozen proposal.",
      "example": "example"
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time",
      "description": "Original explicit acceptance deadline.",
      "example": "2026-12-31T18:00:00.000Z"
    }
  },
  "example": {
    "agreement": {
      "id": "7333b91d-1456-424d-8cf4-d12591cce3e7",
      "action": "CHANGE",
      "state": "PENDING",
      "revision": 1,
      "planHash": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
      "expiresAt": "2026-12-31T18:00:00.000Z",
      "scheduledAt": "2026-01-15T12:00:00.000Z",
      "endsAt": "2026-12-31T18:00:00.000Z",
      "partySize": 1,
      "servicePeriodId": "4846c409-f4df-40f6-81cc-1d7157a5c646",
      "offer": {
        "required": true,
        "terms": null,
        "termsHash": null
      },
      "activatedAgreementVersion": null,
      "activatedReservationRevision": null
    },
    "capability": "example",
    "expiresAt": "2026-12-31T18:00:00.000Z"
  }
}

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"
}

IdempotencyConflictError

Idempotency key is already in progress or was reused with a different payload.

Full definition

{
  "example": {
    "statusCode": 409,
    "error": "errors:http.conflict",
    "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
    "message": "errors:idempotency.inProgress",
    "translationKey": "errors:idempotency.inProgress"
  },
  "allOf": [
    {
      "$ref": "#/components/schemas/TranslatedErrorDto"
    },
    {
      "type": "object",
      "required": [
        "code"
      ],
      "properties": {
        "statusCode": {
          "type": "integer",
          "enum": [
            409
          ],
          "description": "HTTP 409 conflict status.",
          "example": 409
        },
        "code": {
          "type": "string",
          "enum": [
            "IDEMPOTENCY_REQUEST_NOT_READY",
            "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH",
            "IDEMPOTENCY_REQUEST_IN_PROGRESS",
            "IDEMPOTENCY_SCOPE_INCOMPLETE"
          ],
          "description": "Allowed code for idempotency conflict error: IDEMPOTENCY_REQUEST_NOT_READY, IDEMPOTENCY_KEY_PAYLOAD_MISMATCH, IDEMPOTENCY_REQUEST_IN_PROGRESS, IDEMPOTENCY_SCOPE_INCOMPLETE.",
          "example": "IDEMPOTENCY_REQUEST_NOT_READY"
        }
      },
      "example": {
        "code": "IDEMPOTENCY_REQUEST_NOT_READY"
      }
    }
  ],
  "description": "Idempotency key is already in progress or was reused with a different payload."
}