Skip to content
Sections

Guest preorders

Resume a public preorder draft

GET/public/preorders/drafts/{draftReference}

Uses the draft capability to return the unexpired encrypted cart, verification state, and current revision it owns.

Authentication

Authorization: Bearer <HALLIFY_PREORDER_DRAFT_TOKEN>

Guest-owned capability for a public preorder draft.

Connection guide

Parameters

draftReferencePath · Required

Opaque reference identifying the public preorder draft; authorization still requires the separate draft capability.

string
Full definition
{
  "type": "string",
  "example": "example"
}

Responses

200Returns the capability-owned public draft and its allowed next actions.
PreorderPublicGetDraftResultDto
Full definition
{
  "$ref": "#/components/schemas/PreorderPublicGetDraftResultDto"
}
Example response · 200 · application/json
{
  "draftReference": "example-reference",
  "status": "ACTIVE",
  "request": {
    "serviceMode": "DINE_IN",
    "scheduledFor": "2026-01-15T12:00:00.000Z",
    "partySize": 1,
    "salesChannelId": "ff0fa725-ba44-4e7a-82bb-a15650e0a0cc",
    "clientMenuVersionId": "cd2f2c2a-ba73-4579-8e32-52da8388fd05",
    "items": [
      {
        "clientLineId": "example-id",
        "menuItemId": null,
        "menuVariantId": null,
        "quantity": 1,
        "modifierOptionIds": [
          "d251fdb0-274c-4e59-8e7e-b1d90e1433bc"
        ],
        "serviceFlags": [
          "example"
        ]
      }
    ]
  },
  "quote": null,
  "expiresAt": "2026-12-31T18:00:00.000Z",
  "updatedAt": "2026-01-15T13:00:00.000Z"
}
401Rejects a missing, malformed, expired, revoked, or invalid preorderDraftToken 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

PreorderPublicGetDraftResultDto

Returns the capability-owned public draft and its allowed next actions.

draftReferenceRequired

Human- or provider-assigned reference used to reconcile preorder public draft with its source record.

string
Full definition
{
  "type": "string",
  "description": "Human- or provider-assigned reference used to reconcile preorder public draft with its source record.",
  "example": "example-reference"
}
statusRequired

Current lifecycle status of preorder public draft; allowed values are ACTIVE, PENDING_VERIFICATION, VERIFIED, QUOTED, CONSUMED, EXPIRED, CANCELED.

string
Full definition
{
  "type": "string",
  "enum": [
    "ACTIVE",
    "PENDING_VERIFICATION",
    "VERIFIED",
    "QUOTED",
    "CONSUMED",
    "EXPIRED",
    "CANCELED"
  ],
  "description": "Current lifecycle status of preorder public draft; allowed values are ACTIVE, PENDING_VERIFICATION, VERIFIED, QUOTED, CONSUMED, EXPIRED, CANCELED.",
  "example": "ACTIVE"
}
requestRequired

Request details embedded in preorder public draft containing service mode, scheduled for, party size, sales channel id, client menu version id, and items.

object
Full definition
{
  "type": "object",
  "properties": {
    "serviceMode": {
      "type": "string",
      "enum": [
        "DINE_IN",
        "PICKUP",
        "DELIVERY",
        "CATERING"
      ],
      "description": "Allowed service mode for preorder public draft: DINE_IN, PICKUP, DELIVERY, CATERING.",
      "example": "DINE_IN"
    },
    "scheduledFor": {
      "type": "string",
      "format": "date-time",
      "description": "RFC 3339 timestamp for scheduled for; offsets represent the same absolute instant.",
      "example": "2026-01-15T12:00:00.000Z"
    },
    "partySize": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000,
      "description": "Whole-number party size recorded for preorder public draft. Accepted values enforce minimum 1 and maximum 10000.",
      "example": 1
    },
    "salesChannelId": {
      "type": "string",
      "format": "uuid",
      "description": "Hallify UUID identifying sales channel associated with preorder public draft.",
      "example": "ff0fa725-ba44-4e7a-82bb-a15650e0a0cc"
    },
    "clientMenuVersionId": {
      "type": "string",
      "format": "uuid",
      "description": "Hallify UUID identifying client menu version associated with preorder public draft.",
      "example": "cd2f2c2a-ba73-4579-8e32-52da8388fd05"
    },
    "items": {
      "type": "array",
      "minItems": 1,
      "maxItems": 100,
      "items": {
        "type": "object",
        "properties": {
          "clientLineId": {
            "type": "string",
            "description": "Opaque identifier for client line associated with preorder public draft item; clients must not assume UUID syntax.",
            "example": "example-id"
          },
          "menuItemId": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "Hallify UUID identifying menu item associated with preorder public draft item. Null means no value is recorded for this representation.",
            "example": "16ee6f36-c0cb-4311-85e8-2d2b3edea0fd"
          },
          "menuVariantId": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "Hallify UUID identifying menu variant associated with preorder public draft item. Null means no value is recorded for this representation.",
            "example": "94389946-e5d8-4fba-8358-e3a9c8a04b11"
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 999,
            "description": "Whole-number quantity measured in the unit established by the item or line that embeds preorder public draft item. Accepted values enforce minimum 1 and maximum 999.",
            "example": 1
          },
          "modifierOptionIds": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid",
              "example": "d251fdb0-274c-4e59-8e7e-b1d90e1433bc"
            },
            "description": "Hallify UUIDs identifying the modifier option set included in preorder public draft item.",
            "example": [
              "d251fdb0-274c-4e59-8e7e-b1d90e1433bc"
            ]
          },
          "serviceFlags": {
            "type": "array",
            "items": {
              "type": "string",
              "example": "example"
            },
            "description": "Service flags values included as service flags in preorder public draft item.",
            "example": [
              "example"
            ]
          }
        },
        "required": [
          "clientLineId",
          "menuItemId",
          "menuVariantId",
          "quantity",
          "modifierOptionIds",
          "serviceFlags"
        ],
        "example": {
          "clientLineId": "example-id",
          "menuItemId": null,
          "menuVariantId": null,
          "quantity": 1,
          "modifierOptionIds": [
            "d251fdb0-274c-4e59-8e7e-b1d90e1433bc"
          ],
          "serviceFlags": [
            "example"
          ]
        }
      },
      "description": "Items returned in the preorder public draft collection.",
      "example": [
        {
          "clientLineId": "example-id",
          "menuItemId": null,
          "menuVariantId": null,
          "quantity": 1,
          "modifierOptionIds": [
            "d251fdb0-274c-4e59-8e7e-b1d90e1433bc"
          ],
          "serviceFlags": [
            "example"
          ]
        }
      ]
    }
  },
  "required": [
    "serviceMode",
    "scheduledFor",
    "partySize",
    "salesChannelId",
    "clientMenuVersionId",
    "items"
  ],
  "description": "Request details embedded in preorder public draft containing service mode, scheduled for, party size, sales channel id, client menu version id, and items.",
  "example": {
    "serviceMode": "DINE_IN",
    "scheduledFor": "2026-01-15T12:00:00.000Z",
    "partySize": 1,
    "salesChannelId": "ff0fa725-ba44-4e7a-82bb-a15650e0a0cc",
    "clientMenuVersionId": "cd2f2c2a-ba73-4579-8e32-52da8388fd05",
    "items": [
      {
        "clientLineId": "example-id",
        "menuItemId": null,
        "menuVariantId": null,
        "quantity": 1,
        "modifierOptionIds": [
          "d251fdb0-274c-4e59-8e7e-b1d90e1433bc"
        ],
        "serviceFlags": [
          "example"
        ]
      }
    ]
  }
}
quoteRequired

Quote details embedded in preorder public draft containing id, status, reference, currency, subtotal, and discount. Null means no value is recorded for this representation.

object · null
Full definition
{
  "type": "object",
  "nullable": true,
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Hallify UUID identifying preorder public draft quote.",
      "example": "9cf6502c-081b-4f02-8b21-5b6146192a9e"
    },
    "status": {
      "type": "string",
      "enum": [
        "ISSUED",
        "ACCEPTED",
        "DECLINED",
        "EXPIRED",
        "SUPERSEDED"
      ],
      "description": "Current lifecycle status of preorder public draft quote; allowed values are ISSUED, ACCEPTED, DECLINED, EXPIRED, SUPERSEDED.",
      "example": "ISSUED"
    },
    "reference": {
      "type": "string",
      "description": "Human- or provider-assigned reference used to reconcile preorder public draft quote with its source record.",
      "example": "example-reference"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Z]{3}$",
      "description": "ISO 4217 currency code for the monetary values carried by preorder public draft quote.",
      "example": "GEL"
    },
    "subtotal": {
      "type": "string",
      "pattern": "^\\d+\\.\\d{2}$",
      "description": "Decimal monetary subtotal serialized as a string in the currency identified by the `currency` field; zero is a recorded amount, not absence.",
      "example": "1.00"
    },
    "discount": {
      "type": "string",
      "pattern": "^\\d+\\.\\d{2}$",
      "description": "Decimal monetary discount serialized as a string in the currency identified by the `currency` field; zero is a recorded amount, not absence.",
      "example": "1.00"
    },
    "serviceCharge": {
      "type": "string",
      "pattern": "^\\d+\\.\\d{2}$",
      "description": "Decimal monetary service charge serialized as a string in the currency identified by the `currency` field; zero is a recorded amount, not absence.",
      "example": "1.00"
    },
    "tax": {
      "type": "string",
      "pattern": "^\\d+\\.\\d{2}$",
      "description": "Decimal monetary tax serialized as a string in the currency identified by the `currency` field; zero is a recorded amount, not absence.",
      "example": "1.00"
    },
    "deliveryFee": {
      "type": "string",
      "pattern": "^\\d+\\.\\d{2}$",
      "description": "Decimal monetary delivery fee serialized as a string in the currency identified by the `currency` field; zero is a recorded amount, not absence.",
      "example": "1.00"
    },
    "total": {
      "type": "string",
      "pattern": "^\\d+\\.\\d{2}$",
      "description": "Decimal monetary total serialized as a string in the currency identified by the `currency` field; zero is a recorded amount, not absence.",
      "example": "1.00"
    },
    "depositRequired": {
      "type": "string",
      "pattern": "^\\d+\\.\\d{2}$",
      "description": "Deposit required for preorder public draft quote.",
      "example": "1.00"
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time",
      "description": "RFC 3339 timestamp for expires at; offsets represent the same absolute instant.",
      "example": "2026-12-31T18:00:00.000Z"
    }
  },
  "required": [
    "id",
    "status",
    "reference",
    "currency",
    "subtotal",
    "discount",
    "serviceCharge",
    "tax",
    "deliveryFee",
    "total",
    "depositRequired",
    "expiresAt"
  ],
  "description": "Quote details embedded in preorder public draft containing id, status, reference, currency, subtotal, and discount. Null means no value is recorded for this representation.",
  "example": {
    "id": "9cf6502c-081b-4f02-8b21-5b6146192a9e",
    "status": "ISSUED",
    "reference": "example-reference",
    "currency": "GEL",
    "subtotal": "1.00",
    "discount": "1.00",
    "serviceCharge": "1.00",
    "tax": "1.00",
    "deliveryFee": "1.00",
    "total": "1.00",
    "depositRequired": "1.00",
    "expiresAt": "2026-12-31T18:00:00.000Z"
  }
}
expiresAtRequired

RFC 3339 timestamp for expires at; offsets represent the same absolute instant.

string · date-time
Full definition
{
  "type": "string",
  "format": "date-time",
  "description": "RFC 3339 timestamp for expires at; offsets represent the same absolute instant.",
  "example": "2026-12-31T18:00:00.000Z"
}
updatedAtRequired

RFC 3339 timestamp for updated at; offsets represent the same absolute instant.

string · date-time
Full definition
{
  "type": "string",
  "format": "date-time",
  "description": "RFC 3339 timestamp for updated at; offsets represent the same absolute instant.",
  "example": "2026-01-15T13:00:00.000Z"
}
Full definition
{
  "type": "object",
  "properties": {
    "draftReference": {
      "type": "string",
      "description": "Human- or provider-assigned reference used to reconcile preorder public draft with its source record.",
      "example": "example-reference"
    },
    "status": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "PENDING_VERIFICATION",
        "VERIFIED",
        "QUOTED",
        "CONSUMED",
        "EXPIRED",
        "CANCELED"
      ],
      "description": "Current lifecycle status of preorder public draft; allowed values are ACTIVE, PENDING_VERIFICATION, VERIFIED, QUOTED, CONSUMED, EXPIRED, CANCELED.",
      "example": "ACTIVE"
    },
    "request": {
      "type": "object",
      "properties": {
        "serviceMode": {
          "type": "string",
          "enum": [
            "DINE_IN",
            "PICKUP",
            "DELIVERY",
            "CATERING"
          ],
          "description": "Allowed service mode for preorder public draft: DINE_IN, PICKUP, DELIVERY, CATERING.",
          "example": "DINE_IN"
        },
        "scheduledFor": {
          "type": "string",
          "format": "date-time",
          "description": "RFC 3339 timestamp for scheduled for; offsets represent the same absolute instant.",
          "example": "2026-01-15T12:00:00.000Z"
        },
        "partySize": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10000,
          "description": "Whole-number party size recorded for preorder public draft. Accepted values enforce minimum 1 and maximum 10000.",
          "example": 1
        },
        "salesChannelId": {
          "type": "string",
          "format": "uuid",
          "description": "Hallify UUID identifying sales channel associated with preorder public draft.",
          "example": "ff0fa725-ba44-4e7a-82bb-a15650e0a0cc"
        },
        "clientMenuVersionId": {
          "type": "string",
          "format": "uuid",
          "description": "Hallify UUID identifying client menu version associated with preorder public draft.",
          "example": "cd2f2c2a-ba73-4579-8e32-52da8388fd05"
        },
        "items": {
          "type": "array",
          "minItems": 1,
          "maxItems": 100,
          "items": {
            "type": "object",
            "properties": {
              "clientLineId": {
                "type": "string",
                "description": "Opaque identifier for client line associated with preorder public draft item; clients must not assume UUID syntax.",
                "example": "example-id"
              },
              "menuItemId": {
                "type": "string",
                "format": "uuid",
                "nullable": true,
                "description": "Hallify UUID identifying menu item associated with preorder public draft item. Null means no value is recorded for this representation.",
                "example": "16ee6f36-c0cb-4311-85e8-2d2b3edea0fd"
              },
              "menuVariantId": {
                "type": "string",
                "format": "uuid",
                "nullable": true,
                "description": "Hallify UUID identifying menu variant associated with preorder public draft item. Null means no value is recorded for this representation.",
                "example": "94389946-e5d8-4fba-8358-e3a9c8a04b11"
              },
              "quantity": {
                "type": "integer",
                "minimum": 1,
                "maximum": 999,
                "description": "Whole-number quantity measured in the unit established by the item or line that embeds preorder public draft item. Accepted values enforce minimum 1 and maximum 999.",
                "example": 1
              },
              "modifierOptionIds": {
                "type": "array",
                "items": {
                  "type": "string",
                  "format": "uuid",
                  "example": "d251fdb0-274c-4e59-8e7e-b1d90e1433bc"
                },
                "description": "Hallify UUIDs identifying the modifier option set included in preorder public draft item.",
                "example": [
                  "d251fdb0-274c-4e59-8e7e-b1d90e1433bc"
                ]
              },
              "serviceFlags": {
                "type": "array",
                "items": {
                  "type": "string",
                  "example": "example"
                },
                "description": "Service flags values included as service flags in preorder public draft item.",
                "example": [
                  "example"
                ]
              }
            },
            "required": [
              "clientLineId",
              "menuItemId",
              "menuVariantId",
              "quantity",
              "modifierOptionIds",
              "serviceFlags"
            ],
            "example": {
              "clientLineId": "example-id",
              "menuItemId": null,
              "menuVariantId": null,
              "quantity": 1,
              "modifierOptionIds": [
                "d251fdb0-274c-4e59-8e7e-b1d90e1433bc"
              ],
              "serviceFlags": [
                "example"
              ]
            }
          },
          "description": "Items returned in the preorder public draft collection.",
          "example": [
            {
              "clientLineId": "example-id",
              "menuItemId": null,
              "menuVariantId": null,
              "quantity": 1,
              "modifierOptionIds": [
                "d251fdb0-274c-4e59-8e7e-b1d90e1433bc"
              ],
              "serviceFlags": [
                "example"
              ]
            }
          ]
        }
      },
      "required": [
        "serviceMode",
        "scheduledFor",
        "partySize",
        "salesChannelId",
        "clientMenuVersionId",
        "items"
      ],
      "description": "Request details embedded in preorder public draft containing service mode, scheduled for, party size, sales channel id, client menu version id, and items.",
      "example": {
        "serviceMode": "DINE_IN",
        "scheduledFor": "2026-01-15T12:00:00.000Z",
        "partySize": 1,
        "salesChannelId": "ff0fa725-ba44-4e7a-82bb-a15650e0a0cc",
        "clientMenuVersionId": "cd2f2c2a-ba73-4579-8e32-52da8388fd05",
        "items": [
          {
            "clientLineId": "example-id",
            "menuItemId": null,
            "menuVariantId": null,
            "quantity": 1,
            "modifierOptionIds": [
              "d251fdb0-274c-4e59-8e7e-b1d90e1433bc"
            ],
            "serviceFlags": [
              "example"
            ]
          }
        ]
      }
    },
    "quote": {
      "type": "object",
      "nullable": true,
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Hallify UUID identifying preorder public draft quote.",
          "example": "9cf6502c-081b-4f02-8b21-5b6146192a9e"
        },
        "status": {
          "type": "string",
          "enum": [
            "ISSUED",
            "ACCEPTED",
            "DECLINED",
            "EXPIRED",
            "SUPERSEDED"
          ],
          "description": "Current lifecycle status of preorder public draft quote; allowed values are ISSUED, ACCEPTED, DECLINED, EXPIRED, SUPERSEDED.",
          "example": "ISSUED"
        },
        "reference": {
          "type": "string",
          "description": "Human- or provider-assigned reference used to reconcile preorder public draft quote with its source record.",
          "example": "example-reference"
        },
        "currency": {
          "type": "string",
          "pattern": "^[A-Z]{3}$",
          "description": "ISO 4217 currency code for the monetary values carried by preorder public draft quote.",
          "example": "GEL"
        },
        "subtotal": {
          "type": "string",
          "pattern": "^\\d+\\.\\d{2}$",
          "description": "Decimal monetary subtotal serialized as a string in the currency identified by the `currency` field; zero is a recorded amount, not absence.",
          "example": "1.00"
        },
        "discount": {
          "type": "string",
          "pattern": "^\\d+\\.\\d{2}$",
          "description": "Decimal monetary discount serialized as a string in the currency identified by the `currency` field; zero is a recorded amount, not absence.",
          "example": "1.00"
        },
        "serviceCharge": {
          "type": "string",
          "pattern": "^\\d+\\.\\d{2}$",
          "description": "Decimal monetary service charge serialized as a string in the currency identified by the `currency` field; zero is a recorded amount, not absence.",
          "example": "1.00"
        },
        "tax": {
          "type": "string",
          "pattern": "^\\d+\\.\\d{2}$",
          "description": "Decimal monetary tax serialized as a string in the currency identified by the `currency` field; zero is a recorded amount, not absence.",
          "example": "1.00"
        },
        "deliveryFee": {
          "type": "string",
          "pattern": "^\\d+\\.\\d{2}$",
          "description": "Decimal monetary delivery fee serialized as a string in the currency identified by the `currency` field; zero is a recorded amount, not absence.",
          "example": "1.00"
        },
        "total": {
          "type": "string",
          "pattern": "^\\d+\\.\\d{2}$",
          "description": "Decimal monetary total serialized as a string in the currency identified by the `currency` field; zero is a recorded amount, not absence.",
          "example": "1.00"
        },
        "depositRequired": {
          "type": "string",
          "pattern": "^\\d+\\.\\d{2}$",
          "description": "Deposit required for preorder public draft quote.",
          "example": "1.00"
        },
        "expiresAt": {
          "type": "string",
          "format": "date-time",
          "description": "RFC 3339 timestamp for expires at; offsets represent the same absolute instant.",
          "example": "2026-12-31T18:00:00.000Z"
        }
      },
      "required": [
        "id",
        "status",
        "reference",
        "currency",
        "subtotal",
        "discount",
        "serviceCharge",
        "tax",
        "deliveryFee",
        "total",
        "depositRequired",
        "expiresAt"
      ],
      "description": "Quote details embedded in preorder public draft containing id, status, reference, currency, subtotal, and discount. Null means no value is recorded for this representation.",
      "example": {
        "id": "9cf6502c-081b-4f02-8b21-5b6146192a9e",
        "status": "ISSUED",
        "reference": "example-reference",
        "currency": "GEL",
        "subtotal": "1.00",
        "discount": "1.00",
        "serviceCharge": "1.00",
        "tax": "1.00",
        "deliveryFee": "1.00",
        "total": "1.00",
        "depositRequired": "1.00",
        "expiresAt": "2026-12-31T18:00:00.000Z"
      }
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time",
      "description": "RFC 3339 timestamp for expires at; offsets represent the same absolute instant.",
      "example": "2026-12-31T18:00:00.000Z"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "RFC 3339 timestamp for updated at; offsets represent the same absolute instant.",
      "example": "2026-01-15T13:00:00.000Z"
    }
  },
  "required": [
    "draftReference",
    "status",
    "request",
    "quote",
    "expiresAt",
    "updatedAt"
  ],
  "description": "Returns the capability-owned public draft and its allowed next actions.",
  "example": {
    "draftReference": "example-reference",
    "status": "ACTIVE",
    "request": {
      "serviceMode": "DINE_IN",
      "scheduledFor": "2026-01-15T12:00:00.000Z",
      "partySize": 1,
      "salesChannelId": "ff0fa725-ba44-4e7a-82bb-a15650e0a0cc",
      "clientMenuVersionId": "cd2f2c2a-ba73-4579-8e32-52da8388fd05",
      "items": [
        {
          "clientLineId": "example-id",
          "menuItemId": null,
          "menuVariantId": null,
          "quantity": 1,
          "modifierOptionIds": [
            "d251fdb0-274c-4e59-8e7e-b1d90e1433bc"
          ],
          "serviceFlags": [
            "example"
          ]
        }
      ]
    },
    "quote": null,
    "expiresAt": "2026-12-31T18:00:00.000Z",
    "updatedAt": "2026-01-15T13: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"
}

Hallify uses essential cookies and optional analytics.

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