Read an owned reservation or waitlist entry

Authentication

Authorization: Bearer <HALLIFY_RESERVATION_MANAGE_TOKEN>

Guest-owned capability for managing a reservation or waitlist entry.

Connection guide

Parameters

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

Responses

200Returns the capability-owned record, allowed actions, and current revision.

ReservationPublicReadManagedResultDto

Full definition

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

Example response · 200 · application/json

{
  "venue": {
    "id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
    "name": "Example name",
    "timeZone": "Asia/Tbilisi"
  },
  "publicChannel": {
    "id": "3db2ed63-9466-4829-81aa-e4959a2279b0",
    "publicHandle": "example",
    "status": "DRAFT"
  },
  "servicePeriod": {
    "id": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8",
    "name": "Example name",
    "bookingMode": "INSTANT"
  },
  "source": {
    "kind": "RESERVATION",
    "entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
    "venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
    "publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
    "presentation": {
      "kind": "CANONICAL",
      "connectionId": null,
      "resourceId": null,
      "origin": null
    }
  },
  "grantExpiresAt": "2026-12-31T18:00:00.000Z",
  "serverTime": "2026-01-15T12:00:00.000Z",
  "pendingAgreement": null,
  "guarantee": null,
  "kind": "RESERVATION",
  "id": "a42073ae-5313-4ace-86d8-86fb33fde1a9",
  "referenceCode": "EXAMPLE",
  "revision": 1,
  "status": "REQUESTED",
  "partySize": 1,
  "scheduledAt": "2026-01-15T12:00:00.000Z",
  "endsAt": "2026-12-31T18:00:00.000Z",
  "allowedActions": [
    "CONFIRM"
  ]
}

401Rejects a missing, malformed, expired, revoked, or invalid reservationManageToken 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"
}

Schemas

ReservationPublicReadManagedResultDto

Current guest-safe management view under the exact native READ grant and current presentation authority. It is separate from an immutable original command receipt.

Full definition

{
  "description": "Current guest-safe management view under the exact native READ grant and current presentation authority. It is separate from an immutable original command receipt.",
  "oneOf": [
    {
      "type": "object",
      "description": "Current reservation context and capability-scoped native lifecycle actions.",
      "additionalProperties": false,
      "required": [
        "kind",
        "id",
        "referenceCode",
        "revision",
        "status",
        "partySize",
        "scheduledAt",
        "endsAt",
        "venue",
        "publicChannel",
        "servicePeriod",
        "source",
        "grantExpiresAt",
        "serverTime",
        "allowedActions",
        "guarantee",
        "pendingAgreement"
      ],
      "properties": {
        "venue": {
          "type": "object",
          "description": "Current native venue display and scheduling context.",
          "additionalProperties": false,
          "required": [
            "id",
            "name",
            "timeZone"
          ],
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid",
              "description": "Owning venue UUID.",
              "example": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0"
            },
            "name": {
              "type": "string",
              "description": "Current public venue name.",
              "example": "Example name"
            },
            "timeZone": {
              "type": "string",
              "description": "Native venue IANA time zone.",
              "example": "Asia/Tbilisi"
            }
          },
          "example": {
            "id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
            "name": "Example name",
            "timeZone": "Asia/Tbilisi"
          }
        },
        "publicChannel": {
          "type": "object",
          "description": "The owner record's native public channel, independent of the storefront presentation handle. Its current status does not replace continuation authorization.",
          "additionalProperties": false,
          "required": [
            "id",
            "publicHandle",
            "status"
          ],
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid",
              "description": "Native channel UUID.",
              "example": "3db2ed63-9466-4829-81aa-e4959a2279b0"
            },
            "publicHandle": {
              "type": "string",
              "description": "Native reservation channel handle.",
              "example": "example"
            },
            "status": {
              "type": "string",
              "description": "Current native public-channel lifecycle.",
              "enum": [
                "DRAFT",
                "ACTIVE",
                "PAUSED"
              ],
              "example": "DRAFT"
            }
          },
          "example": {
            "id": "3db2ed63-9466-4829-81aa-e4959a2279b0",
            "publicHandle": "example",
            "status": "DRAFT"
          }
        },
        "servicePeriod": {
          "type": "object",
          "description": "Current native service-period identity and booking mode.",
          "additionalProperties": false,
          "required": [
            "id",
            "name",
            "bookingMode"
          ],
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid",
              "description": "Native service-period UUID.",
              "example": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8"
            },
            "name": {
              "type": "string",
              "description": "Current service-period name.",
              "example": "Example name"
            },
            "bookingMode": {
              "type": "string",
              "description": "Current service-period mode; it does not rewrite an original booking receipt.",
              "enum": [
                "INSTANT",
                "REQUEST"
              ],
              "example": "INSTANT"
            }
          },
          "example": {
            "id": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8",
            "name": "Example name",
            "bookingMode": "INSTANT"
          }
        },
        "source": {
          "type": "object",
          "description": "Nonsecret exact native owner tuple and the original grant presentation. These identifiers do not grant authority or permit switching origins, connections or capabilities.",
          "additionalProperties": false,
          "required": [
            "kind",
            "entityId",
            "venueId",
            "publicChannelId",
            "presentation"
          ],
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "RESERVATION",
                "WAITLIST"
              ],
              "description": "Native owner kind.",
              "example": "RESERVATION"
            },
            "entityId": {
              "type": "string",
              "format": "uuid",
              "description": "Exact reservation or waitlist owner UUID.",
              "example": "6b288694-8b6d-49cd-8007-264ca7224921"
            },
            "venueId": {
              "type": "string",
              "format": "uuid",
              "description": "Native owner venue UUID.",
              "example": "0604de3a-da74-4ad5-89f6-2dfe000d5391"
            },
            "publicChannelId": {
              "type": "string",
              "format": "uuid",
              "description": "Native owner channel UUID.",
              "example": "9bee613d-3322-4a03-8b9f-8a6259984eee"
            },
            "presentation": {
              "type": "object",
              "description": "Immutable issuance classification. CANONICAL has null Storefront fields; STOREFRONT retains the exact original connection, attached resource and request Origin.",
              "additionalProperties": false,
              "required": [
                "kind",
                "connectionId",
                "resourceId",
                "origin"
              ],
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "CANONICAL",
                    "STOREFRONT"
                  ],
                  "description": "Original grant issuance context.",
                  "example": "CANONICAL"
                },
                "connectionId": {
                  "type": "string",
                  "format": "uuid",
                  "nullable": true,
                  "description": "Original Storefront connection UUID, or null for canonical issuance.",
                  "example": "2fde64d5-54a3-47d0-800f-a015f92a8878"
                },
                "resourceId": {
                  "type": "string",
                  "format": "uuid",
                  "nullable": true,
                  "description": "Original attached Storefront resource UUID, or null for canonical issuance.",
                  "example": "d5b5eb29-9b8d-4d6f-8f4f-6f0e58f32568"
                },
                "origin": {
                  "type": "string",
                  "format": "uri",
                  "nullable": true,
                  "description": "Exact original Storefront browser Origin, or null for canonical issuance.",
                  "example": "https://example.test/resource"
                }
              },
              "example": {
                "kind": "CANONICAL",
                "connectionId": null,
                "resourceId": null,
                "origin": null
              }
            }
          },
          "example": {
            "kind": "RESERVATION",
            "entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
            "venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
            "publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
            "presentation": {
              "kind": "CANONICAL",
              "connectionId": null,
              "resourceId": null,
              "origin": null
            }
          }
        },
        "grantExpiresAt": {
          "type": "string",
          "format": "date-time",
          "description": "Original native manage-capability expiry; reading does not renew it.",
          "example": "2026-12-31T18:00:00.000Z"
        },
        "serverTime": {
          "type": "string",
          "format": "date-time",
          "description": "Server instant used for current action and claim-deadline eligibility.",
          "example": "2026-01-15T12:00:00.000Z"
        },
        "pendingAgreement": {
          "type": "object",
          "description": "Current pending proposal or accepted continuation, or null; it has not changed the actual native slot before activation.",
          "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": "5a694cf6-acf7-40fd-81e6-92ec0fa6c91f"
            },
            "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
            }
          },
          "nullable": true,
          "example": {
            "id": "5a694cf6-acf7-40fd-81e6-92ec0fa6c91f",
            "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
          }
        },
        "guarantee": {
          "type": "object",
          "nullable": true,
          "description": "Actual native guarantee and its immutable original accepted terms, or null when no obligation exists.",
          "required": [
            "id",
            "kind",
            "status",
            "amount",
            "currency",
            "dueAt",
            "termsHash",
            "terms",
            "authorizationExpiresAt"
          ],
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid",
              "description": "Actual native guarantee UUID.",
              "example": "d8c59877-4141-422c-8bcd-eb23a54e43ad"
            },
            "kind": {
              "type": "string",
              "enum": [
                "DEPOSIT",
                "CARD_HOLD",
                "PREPAID"
              ],
              "description": "Original guarantee kind.",
              "example": "DEPOSIT"
            },
            "status": {
              "type": "string",
              "enum": [
                "PENDING",
                "SATISFIED",
                "WAIVED",
                "EXPIRED",
                "REFUNDED",
                "FORFEITED"
              ],
              "description": "Current native guarantee lifecycle.",
              "example": "PENDING"
            },
            "amount": {
              "type": "string",
              "pattern": "^(0|[1-9][0-9]{0,9})\\.[0-9]{2}$",
              "description": "Original exact native guarantee principal.",
              "example": "1.00"
            },
            "currency": {
              "type": "string",
              "pattern": "^[A-Z]{3}$",
              "description": "Original native currency.",
              "example": "GEL"
            },
            "dueAt": {
              "type": "string",
              "format": "date-time",
              "nullable": true,
              "description": "Original payment deadline, or null for legacy evidence.",
              "example": "2026-12-31T18:00:00.000Z"
            },
            "termsHash": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}$",
              "nullable": true,
              "description": "Immutable accepted terms digest, or null for legacy evidence.",
              "example": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
            },
            "terms": {
              "type": "object",
              "description": "Original accepted native guarantee terms, or null for legacy evidence.",
              "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"
              }
            },
            "authorizationExpiresAt": {
              "type": "string",
              "format": "date-time",
              "nullable": true,
              "description": "Proven PSP authorization expiry, or null without authenticated evidence.",
              "example": "2026-12-31T18:00:00.000Z"
            }
          },
          "example": {
            "id": "d8c59877-4141-422c-8bcd-eb23a54e43ad",
            "kind": "DEPOSIT",
            "status": "PENDING",
            "amount": "1.00",
            "currency": "GEL",
            "dueAt": null,
            "termsHash": null,
            "terms": null,
            "authorizationExpiresAt": null
          }
        },
        "kind": {
          "type": "string",
          "enum": [
            "RESERVATION"
          ],
          "description": "Native owner kind.",
          "example": "RESERVATION"
        },
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Capability-owned reservation UUID.",
          "example": "a42073ae-5313-4ace-86d8-86fb33fde1a9"
        },
        "referenceCode": {
          "type": "string",
          "description": "Guest-facing reference code.",
          "example": "EXAMPLE"
        },
        "revision": {
          "type": "integer",
          "minimum": 1,
          "description": "Current native reservation revision.",
          "example": 1
        },
        "status": {
          "type": "string",
          "enum": [
            "REQUESTED",
            "BOOKED",
            "CONFIRMED",
            "ARRIVED",
            "SEATED",
            "CANCELED",
            "NO_SHOW",
            "DECLINED",
            "EXPIRED"
          ],
          "description": "Current native reservation lifecycle.",
          "example": "REQUESTED"
        },
        "partySize": {
          "type": "integer",
          "minimum": 1,
          "maximum": 99,
          "description": "Current number of guests.",
          "example": 1
        },
        "scheduledAt": {
          "type": "string",
          "format": "date-time",
          "description": "Current scheduled arrival instant.",
          "example": "2026-01-15T12:00:00.000Z"
        },
        "endsAt": {
          "type": "string",
          "format": "date-time",
          "description": "Current scheduled reservation end.",
          "example": "2026-12-31T18:00:00.000Z"
        },
        "allowedActions": {
          "type": "array",
          "description": "Actions currently allowed by lifecycle and grant scopes. Execution still rechecks revision, presentation, commercial admission, rules and capacity.",
          "uniqueItems": true,
          "maxItems": 3,
          "items": {
            "type": "string",
            "enum": [
              "CONFIRM",
              "CHANGE",
              "CANCEL"
            ],
            "description": "Available native guest command.",
            "example": "CONFIRM"
          },
          "example": [
            "CONFIRM"
          ]
        }
      },
      "example": {
        "venue": {
          "id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
          "name": "Example name",
          "timeZone": "Asia/Tbilisi"
        },
        "publicChannel": {
          "id": "3db2ed63-9466-4829-81aa-e4959a2279b0",
          "publicHandle": "example",
          "status": "DRAFT"
        },
        "servicePeriod": {
          "id": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8",
          "name": "Example name",
          "bookingMode": "INSTANT"
        },
        "source": {
          "kind": "RESERVATION",
          "entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
          "venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
          "publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
          "presentation": {
            "kind": "CANONICAL",
            "connectionId": null,
            "resourceId": null,
            "origin": null
          }
        },
        "grantExpiresAt": "2026-12-31T18:00:00.000Z",
        "serverTime": "2026-01-15T12:00:00.000Z",
        "pendingAgreement": null,
        "guarantee": null,
        "kind": "RESERVATION",
        "id": "a42073ae-5313-4ace-86d8-86fb33fde1a9",
        "referenceCode": "EXAMPLE",
        "revision": 1,
        "status": "REQUESTED",
        "partySize": 1,
        "scheduledAt": "2026-01-15T12:00:00.000Z",
        "endsAt": "2026-12-31T18:00:00.000Z",
        "allowedActions": [
          "CONFIRM"
        ]
      }
    },
    {
      "type": "object",
      "description": "Current waitlist context, safe wait estimate and capability-scoped native lifecycle actions.",
      "additionalProperties": false,
      "required": [
        "kind",
        "id",
        "referenceCode",
        "revision",
        "status",
        "partySize",
        "claimExpiresAt",
        "quotedWaitMinMinutes",
        "quotedWaitMaxMinutes",
        "estimatedSeatAt",
        "venue",
        "publicChannel",
        "servicePeriod",
        "source",
        "grantExpiresAt",
        "serverTime",
        "allowedActions"
      ],
      "properties": {
        "venue": {
          "type": "object",
          "description": "Current native venue display and scheduling context.",
          "additionalProperties": false,
          "required": [
            "id",
            "name",
            "timeZone"
          ],
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid",
              "description": "Owning venue UUID.",
              "example": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0"
            },
            "name": {
              "type": "string",
              "description": "Current public venue name.",
              "example": "Example name"
            },
            "timeZone": {
              "type": "string",
              "description": "Native venue IANA time zone.",
              "example": "Asia/Tbilisi"
            }
          },
          "example": {
            "id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
            "name": "Example name",
            "timeZone": "Asia/Tbilisi"
          }
        },
        "publicChannel": {
          "type": "object",
          "description": "The owner record's native public channel, independent of the storefront presentation handle. Its current status does not replace continuation authorization.",
          "additionalProperties": false,
          "required": [
            "id",
            "publicHandle",
            "status"
          ],
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid",
              "description": "Native channel UUID.",
              "example": "3db2ed63-9466-4829-81aa-e4959a2279b0"
            },
            "publicHandle": {
              "type": "string",
              "description": "Native reservation channel handle.",
              "example": "example"
            },
            "status": {
              "type": "string",
              "description": "Current native public-channel lifecycle.",
              "enum": [
                "DRAFT",
                "ACTIVE",
                "PAUSED"
              ],
              "example": "DRAFT"
            }
          },
          "example": {
            "id": "3db2ed63-9466-4829-81aa-e4959a2279b0",
            "publicHandle": "example",
            "status": "DRAFT"
          }
        },
        "servicePeriod": {
          "type": "object",
          "description": "Current native service-period identity and booking mode.",
          "additionalProperties": false,
          "required": [
            "id",
            "name",
            "bookingMode"
          ],
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid",
              "description": "Native service-period UUID.",
              "example": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8"
            },
            "name": {
              "type": "string",
              "description": "Current service-period name.",
              "example": "Example name"
            },
            "bookingMode": {
              "type": "string",
              "description": "Current service-period mode; it does not rewrite an original booking receipt.",
              "enum": [
                "INSTANT",
                "REQUEST"
              ],
              "example": "INSTANT"
            }
          },
          "example": {
            "id": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8",
            "name": "Example name",
            "bookingMode": "INSTANT"
          }
        },
        "source": {
          "type": "object",
          "description": "Nonsecret exact native owner tuple and the original grant presentation. These identifiers do not grant authority or permit switching origins, connections or capabilities.",
          "additionalProperties": false,
          "required": [
            "kind",
            "entityId",
            "venueId",
            "publicChannelId",
            "presentation"
          ],
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "RESERVATION",
                "WAITLIST"
              ],
              "description": "Native owner kind.",
              "example": "RESERVATION"
            },
            "entityId": {
              "type": "string",
              "format": "uuid",
              "description": "Exact reservation or waitlist owner UUID.",
              "example": "6b288694-8b6d-49cd-8007-264ca7224921"
            },
            "venueId": {
              "type": "string",
              "format": "uuid",
              "description": "Native owner venue UUID.",
              "example": "0604de3a-da74-4ad5-89f6-2dfe000d5391"
            },
            "publicChannelId": {
              "type": "string",
              "format": "uuid",
              "description": "Native owner channel UUID.",
              "example": "9bee613d-3322-4a03-8b9f-8a6259984eee"
            },
            "presentation": {
              "type": "object",
              "description": "Immutable issuance classification. CANONICAL has null Storefront fields; STOREFRONT retains the exact original connection, attached resource and request Origin.",
              "additionalProperties": false,
              "required": [
                "kind",
                "connectionId",
                "resourceId",
                "origin"
              ],
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "CANONICAL",
                    "STOREFRONT"
                  ],
                  "description": "Original grant issuance context.",
                  "example": "CANONICAL"
                },
                "connectionId": {
                  "type": "string",
                  "format": "uuid",
                  "nullable": true,
                  "description": "Original Storefront connection UUID, or null for canonical issuance.",
                  "example": "2fde64d5-54a3-47d0-800f-a015f92a8878"
                },
                "resourceId": {
                  "type": "string",
                  "format": "uuid",
                  "nullable": true,
                  "description": "Original attached Storefront resource UUID, or null for canonical issuance.",
                  "example": "d5b5eb29-9b8d-4d6f-8f4f-6f0e58f32568"
                },
                "origin": {
                  "type": "string",
                  "format": "uri",
                  "nullable": true,
                  "description": "Exact original Storefront browser Origin, or null for canonical issuance.",
                  "example": "https://example.test/resource"
                }
              },
              "example": {
                "kind": "CANONICAL",
                "connectionId": null,
                "resourceId": null,
                "origin": null
              }
            }
          },
          "example": {
            "kind": "RESERVATION",
            "entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
            "venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
            "publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
            "presentation": {
              "kind": "CANONICAL",
              "connectionId": null,
              "resourceId": null,
              "origin": null
            }
          }
        },
        "grantExpiresAt": {
          "type": "string",
          "format": "date-time",
          "description": "Original native manage-capability expiry; reading does not renew it.",
          "example": "2026-12-31T18:00:00.000Z"
        },
        "serverTime": {
          "type": "string",
          "format": "date-time",
          "description": "Server instant used for current action and claim-deadline eligibility.",
          "example": "2026-01-15T12:00:00.000Z"
        },
        "kind": {
          "type": "string",
          "enum": [
            "WAITLIST"
          ],
          "description": "Native owner kind.",
          "example": "WAITLIST"
        },
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Capability-owned waitlist entry UUID.",
          "example": "a7476fce-e842-42a4-896a-c23b0e88b420"
        },
        "referenceCode": {
          "type": "string",
          "description": "Guest-facing reference code.",
          "example": "EXAMPLE"
        },
        "revision": {
          "type": "integer",
          "minimum": 1,
          "description": "Current native waitlist revision.",
          "example": 1
        },
        "status": {
          "type": "string",
          "enum": [
            "WAITING",
            "NOTIFIED",
            "CLAIMED",
            "SKIPPED",
            "SEATED",
            "CANCELED",
            "NO_SHOW"
          ],
          "description": "Current native waitlist lifecycle.",
          "example": "WAITING"
        },
        "partySize": {
          "type": "integer",
          "minimum": 1,
          "maximum": 99,
          "description": "Current number of guests.",
          "example": 1
        },
        "claimExpiresAt": {
          "type": "string",
          "format": "date-time",
          "nullable": true,
          "description": "Native accepted-offer claim deadline, or null without a current window.",
          "example": "2026-12-31T18:00:00.000Z"
        },
        "quotedWaitMinMinutes": {
          "type": "integer",
          "nullable": true,
          "description": "Current native minimum wait estimate in minutes, or null when unknown.",
          "example": 0
        },
        "quotedWaitMaxMinutes": {
          "type": "integer",
          "nullable": true,
          "description": "Current native maximum wait estimate in minutes, or null when unknown.",
          "example": 0
        },
        "estimatedSeatAt": {
          "type": "string",
          "format": "date-time",
          "nullable": true,
          "description": "Current native estimated seating instant, or null when unknown.",
          "example": "2026-01-15T12:00:00.000Z"
        },
        "allowedActions": {
          "type": "array",
          "description": "Actions currently allowed by lifecycle, grant scopes and the native claim deadline. CLAIM changes the waitlist to CLAIMED and does not create a reservation.",
          "uniqueItems": true,
          "maxItems": 2,
          "items": {
            "type": "string",
            "enum": [
              "CLAIM",
              "CANCEL"
            ],
            "description": "Available native guest waitlist command.",
            "example": "CLAIM"
          },
          "example": [
            "CLAIM"
          ]
        }
      },
      "example": {
        "venue": {
          "id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
          "name": "Example name",
          "timeZone": "Asia/Tbilisi"
        },
        "publicChannel": {
          "id": "3db2ed63-9466-4829-81aa-e4959a2279b0",
          "publicHandle": "example",
          "status": "DRAFT"
        },
        "servicePeriod": {
          "id": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8",
          "name": "Example name",
          "bookingMode": "INSTANT"
        },
        "source": {
          "kind": "RESERVATION",
          "entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
          "venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
          "publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
          "presentation": {
            "kind": "CANONICAL",
            "connectionId": null,
            "resourceId": null,
            "origin": null
          }
        },
        "grantExpiresAt": "2026-12-31T18:00:00.000Z",
        "serverTime": "2026-01-15T12:00:00.000Z",
        "kind": "WAITLIST",
        "id": "a7476fce-e842-42a4-896a-c23b0e88b420",
        "referenceCode": "EXAMPLE",
        "revision": 1,
        "status": "WAITING",
        "partySize": 1,
        "claimExpiresAt": null,
        "quotedWaitMinMinutes": null,
        "quotedWaitMaxMinutes": null,
        "estimatedSeatAt": null,
        "allowedActions": [
          "CLAIM"
        ]
      }
    }
  ],
  "example": {
    "venue": {
      "id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
      "name": "Example name",
      "timeZone": "Asia/Tbilisi"
    },
    "publicChannel": {
      "id": "3db2ed63-9466-4829-81aa-e4959a2279b0",
      "publicHandle": "example",
      "status": "DRAFT"
    },
    "servicePeriod": {
      "id": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8",
      "name": "Example name",
      "bookingMode": "INSTANT"
    },
    "source": {
      "kind": "RESERVATION",
      "entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
      "venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
      "publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
      "presentation": {
        "kind": "CANONICAL",
        "connectionId": null,
        "resourceId": null,
        "origin": null
      }
    },
    "grantExpiresAt": "2026-12-31T18:00:00.000Z",
    "serverTime": "2026-01-15T12:00:00.000Z",
    "pendingAgreement": null,
    "guarantee": null,
    "kind": "RESERVATION",
    "id": "a42073ae-5313-4ace-86d8-86fb33fde1a9",
    "referenceCode": "EXAMPLE",
    "revision": 1,
    "status": "REQUESTED",
    "partySize": 1,
    "scheduledAt": "2026-01-15T12:00:00.000Z",
    "endsAt": "2026-12-31T18:00:00.000Z",
    "allowedActions": [
      "CONFIRM"
    ]
  }
}

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