Authentication
Authorization: Bearer <HALLIFY_PREORDER_DRAFT_TOKEN>Guest-owned capability for a public preorder draft.
Parameters
draftReferencePath · RequiredOpaque reference identifying the public preorder draft; authorization still requires the separate draft capability.
stringFull definition
{ "type": "string", "example": "example" }
Responses
200Returns the capability-owned public draft and its allowed next actions.
Full definition
{
"$ref": "#/components/schemas/PreorderPublicGetDraftResultDto"
}{
"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.
Full definition
{
"$ref": "#/components/schemas/TranslatedErrorDto"
}{
"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.
draftReferenceRequiredHuman- or provider-assigned reference used to reconcile preorder public draft with its source record.
stringFull definition
{ "type": "string", "description": "Human- or provider-assigned reference used to reconcile preorder public draft with its source record.", "example": "example-reference" }statusRequiredCurrent lifecycle status of preorder public draft; allowed values are ACTIVE, PENDING_VERIFICATION, VERIFIED, QUOTED, CONSUMED, EXPIRED, CANCELED.
stringFull 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" }requestRequiredRequest details embedded in preorder public draft containing service mode, scheduled for, party size, sales channel id, client menu version id, and items.
objectFull 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" ] } ] } }quoteRequiredQuote details embedded in preorder public draft containing id, status, reference, currency, subtotal, and discount. Null means no value is recorded for this representation.
object · nullFull 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" } }expiresAtRequiredRFC 3339 timestamp for expires at; offsets represent the same absolute instant.
string · date-timeFull 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" }updatedAtRequiredRFC 3339 timestamp for updated at; offsets represent the same absolute instant.
string · date-timeFull 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.
statusCodeRequiredHTTP status code repeated from the response.
integerFull definition
{ "type": "integer", "description": "HTTP status code repeated from the response.", "example": 400 }errorRequiredTranslation key for the HTTP category, such as errors:http.conflict. The specific cause is identified by code and translationKey.
stringFull 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" }codeRequiredStable 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.
stringFull 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." }messageRequiredTranslation key, identical to translationKey. The API does not return localized display text. Resolve the key and translationValues in the consuming application.
stringFull 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." }translationKeyRequiredCanonical 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.
stringFull 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." }translationValuesOptionalOptional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.
objectFull 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" } }validationErrorsOptionalField validation failures with translation keys and stable validator codes. Submitted values and raw validator text are not included.
arrayFull 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" } ] }detailsOptionalOptional domain-specific blocker or validation details
oneOfFull 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.
fieldRequiredPublic field path. Nested properties and array indices are separated by dots.
stringFull definition
{ "type": "string", "example": "email", "description": "Public field path. Nested properties and array indices are separated by dots." }translationKeyRequiredTranslation key for this validator, identical to message. Resolve it using a client dictionary; see the public Developers error catalog.
stringFull 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." }codeRequiredStable validator identifier for this field failure. Custom validators may define additional identifiers.
stringFull definition
{ "type": "string", "example": "isEmail", "description": "Stable validator identifier for this field failure. Custom validators may define additional identifiers." }messageRequiredTranslation key describing this field validation failure, identical to translationKey. Submitted values and validator prose are not included.
stringFull 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." }translationValuesOptionalOptional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.
objectFull 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"
}