Skip to content
HallifyDevelopersSearch documentation
Open Hallify
Sections

Published storefronts

List attached outlets for a verified widget frame

GET/public/storefront-widgets/{connectionId}/outlets

Revalidates the signed widget presentation proof, actual isolated frame origin, current connection generation and exact parent binding before returning one bounded page of explicitly attached brand outlets. Native preorder and reservation discovery use the existing scoped batch projectors. This operation grants no shared cart, guest or payment authority across outlets.

Authentication

x-hallify-widget-context: <HALLIFY_STOREFRONT_WIDGET_CONTEXT>

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

Connection guide

Parameters

connectionIdPath · Required

Exact widget connection UUID retained in the signed presentation proof.

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

Maximum number of results. The server applies twenty when omitted.

integer
Full definition
{
  "minimum": 1,
  "maximum": 50,
  "default": 20,
  "type": "integer",
  "example": 20
}
cursorQuery · Optional

Opaque continuation cursor from the preceding page for the same scope and ordering.

string
Full definition
{
  "minLength": 1,
  "maxLength": 256,
  "type": "string",
  "example": "example"
}
OriginHeader · Required

Actual configured isolated frame origin.

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

Responses

200Private no-store bounded outlet page for the exact widget brand and current parent authority.

Response headers

Cache-Control

Widget outlet authority must be revalidated for each read.

string
Full definition
{
  "type": "string",
  "enum": [
    "no-store"
  ],
  "example": "no-store"
}
StorefrontPublicOutletPageDto
Full definition
{
  "$ref": "#/components/schemas/StorefrontPublicOutletPageDto"
}
Example response · 200 · application/json
{
  "items": [
    {
      "storefrontId": "26a6ca08-40bb-46b0-88cb-edd7b56e8643",
      "venue": {
        "venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
        "name": "Example name",
        "currency": "GEL",
        "timeZone": "Asia/Tbilisi",
        "countryCode": null,
        "city": null,
        "region": null
      },
      "ordering": null,
      "reservations": null
    }
  ],
  "nextCursor": null
}
400The connection UUID, page limit or scope-bound cursor is malformed or invalid.
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 400 · application/json
{
  "statusCode": 400,
  "error": "errors:http.badRequest",
  "code": "HTTP_BAD_REQUEST",
  "message": "errors:http.badRequest",
  "translationKey": "errors:http.badRequest"
}
401The required widget context credential is absent, malformed, expired or has an invalid signature. Error code: STOREFRONT_WIDGET_CONTEXT_INVALID.
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"
}
404The signed context does not match this connection or actual frame origin, or current widget, parent binding or published brand authority is unavailable. Error code: STOREFRONT_PRESENTATION_UNAVAILABLE.
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 404 · application/json
{
  "statusCode": 404,
  "error": "errors:http.notFound",
  "code": "HTTP_NOT_FOUND",
  "message": "errors:http.notFound",
  "translationKey": "errors:http.notFound"
}
503Widget configuration or signing keys are unavailable, or scoped native discovery cannot be safely projected.
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 503 · application/json
{
  "statusCode": 503,
  "error": "errors:http.serviceUnavailable",
  "code": "HTTP_SERVICE_UNAVAILABLE",
  "message": "errors:http.serviceUnavailable",
  "translationKey": "errors:http.serviceUnavailable"
}

Schemas

StorefrontPublicOutletPageDto

Bounded public brand outlet directory page containing safe venue entries and a nullable opaque continuation cursor.

itemsRequired

Bounded outlet directory page.

array
Full definition
{
  "description": "Bounded outlet directory page.",
  "maxItems": 50,
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/StorefrontPublicOutletDto"
  },
  "example": [
    {
      "storefrontId": "26a6ca08-40bb-46b0-88cb-edd7b56e8643",
      "venue": {
        "venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
        "name": "Example name",
        "currency": "GEL",
        "timeZone": "Asia/Tbilisi",
        "countryCode": null,
        "city": null,
        "region": null
      },
      "ordering": null,
      "reservations": null
    }
  ]
}
nextCursorRequired

Opaque continuation cursor, or null when the directory page is final.

string · null
Full definition
{
  "type": "string",
  "description": "Opaque continuation cursor, or null when the directory page is final.",
  "nullable": true,
  "minLength": 1,
  "maxLength": 256,
  "example": "example"
}
Full definition
{
  "type": "object",
  "properties": {
    "items": {
      "description": "Bounded outlet directory page.",
      "maxItems": 50,
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StorefrontPublicOutletDto"
      },
      "example": [
        {
          "storefrontId": "26a6ca08-40bb-46b0-88cb-edd7b56e8643",
          "venue": {
            "venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
            "name": "Example name",
            "currency": "GEL",
            "timeZone": "Asia/Tbilisi",
            "countryCode": null,
            "city": null,
            "region": null
          },
          "ordering": null,
          "reservations": null
        }
      ]
    },
    "nextCursor": {
      "type": "string",
      "description": "Opaque continuation cursor, or null when the directory page is final.",
      "nullable": true,
      "minLength": 1,
      "maxLength": 256,
      "example": "example"
    }
  },
  "description": "Bounded public brand outlet directory page containing safe venue entries and a nullable opaque continuation cursor.",
  "required": [
    "items",
    "nextCursor"
  ],
  "example": {
    "items": [
      {
        "storefrontId": "26a6ca08-40bb-46b0-88cb-edd7b56e8643",
        "venue": {
          "venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
          "name": "Example name",
          "currency": "GEL",
          "timeZone": "Asia/Tbilisi",
          "countryCode": null,
          "city": null,
          "region": null
        },
        "ordering": null,
        "reservations": null
      }
    ],
    "nextCursor": null
  }
}
StorefrontPublicOutletDto

Public brand directory entry pairing an actual venue profile with its explicitly selected venue storefront identity.

storefrontIdRequired

Explicit venue storefront UUID in this brand directory.

string · uuid
Full definition
{
  "type": "string",
  "description": "Explicit venue storefront UUID in this brand directory.",
  "format": "uuid",
  "example": "26a6ca08-40bb-46b0-88cb-edd7b56e8643"
}
venueRequired

Safe public profile for this actual venue.

allOf
Full definition
{
  "description": "Safe public profile for this actual venue.",
  "allOf": [
    {
      "$ref": "#/components/schemas/StorefrontPublicVenueProfileDto"
    }
  ],
  "example": {
    "venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
    "name": "Example name",
    "currency": "GEL",
    "timeZone": "Asia/Tbilisi",
    "countryCode": null,
    "city": null,
    "region": null
  }
}
orderingRequired

Current attached active native preorder channel for this outlet and presentation connection, or null when none is available. This nonsecret discovery does not authorize an order or payment.

object · null
Full definition
{
  "description": "Current attached active native preorder channel for this outlet and presentation connection, or null when none is available. This nonsecret discovery does not authorize an order or payment.",
  "nullable": true,
  "type": "object",
  "properties": {
    "connectionId": {
      "type": "string",
      "description": "Presentation connection UUID to retain as the nonsecret connection locator on native public draft requests. This does not replace current request-origin authorization.",
      "format": "uuid",
      "example": "2fde64d5-54a3-47d0-800f-a015f92a8878"
    },
    "resourceId": {
      "type": "string",
      "description": "Current attached PREORDER resource UUID within the presentation connection and selected venue. This is a discovery locator, not a capability.",
      "format": "uuid",
      "example": "d5b5eb29-9b8d-4d6f-8f4f-6f0e58f32568"
    },
    "venueId": {
      "type": "string",
      "description": "Actual native venue UUID owning this attachment and preorder channel. Orders remain scoped to this venue.",
      "format": "uuid",
      "example": "0604de3a-da74-4ad5-89f6-2dfe000d5391"
    },
    "publicChannelId": {
      "type": "string",
      "description": "Active native preorder public channel UUID belonging to the selected venue.",
      "format": "uuid",
      "example": "9bee613d-3322-4a03-8b9f-8a6259984eee"
    },
    "publicChannelHandle": {
      "type": "string",
      "description": "Native preorder channel discovery handle used by the public catalog. This is distinct from the enclosing storefront presentation handle.",
      "minLength": 1,
      "maxLength": 48,
      "example": "example"
    }
  },
  "required": [
    "connectionId",
    "resourceId",
    "venueId",
    "publicChannelId",
    "publicChannelHandle"
  ],
  "example": {
    "connectionId": "2fde64d5-54a3-47d0-800f-a015f92a8878",
    "resourceId": "d5b5eb29-9b8d-4d6f-8f4f-6f0e58f32568",
    "venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
    "publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
    "publicChannelHandle": "example"
  }
}
reservationsRequired

Current attached active native reservation channel for this outlet and presentation connection, or null when none is available. This nonsecret discovery grants no booking, waitlist, guest or financial authority.

object · null
Full definition
{
  "description": "Current attached active native reservation channel for this outlet and presentation connection, or null when none is available. This nonsecret discovery grants no booking, waitlist, guest or financial authority.",
  "nullable": true,
  "type": "object",
  "properties": {
    "connectionId": {
      "type": "string",
      "description": "Presentation connection UUID used only as the nonsecret connection locator for native public reservation requests. This does not replace current request-origin authorization.",
      "format": "uuid",
      "example": "2fde64d5-54a3-47d0-800f-a015f92a8878"
    },
    "resourceId": {
      "type": "string",
      "description": "Current attached RESERVATION resource UUID within this presentation connection and venue. This is a discovery locator, not a capability.",
      "format": "uuid",
      "example": "d5b5eb29-9b8d-4d6f-8f4f-6f0e58f32568"
    },
    "venueId": {
      "type": "string",
      "description": "Actual native venue UUID owning this attachment and reservation channel. Booking and waitlist demand remain scoped to this venue.",
      "format": "uuid",
      "example": "0604de3a-da74-4ad5-89f6-2dfe000d5391"
    },
    "publicChannelId": {
      "type": "string",
      "description": "Active native reservation public channel UUID belonging to the selected venue.",
      "format": "uuid",
      "example": "9bee613d-3322-4a03-8b9f-8a6259984eee"
    },
    "publicChannelHandle": {
      "type": "string",
      "description": "Native reservation channel discovery handle used by public booking configuration and availability. This is distinct from the enclosing storefront presentation handle.",
      "minLength": 1,
      "maxLength": 48,
      "example": "1.000"
    }
  },
  "required": [
    "connectionId",
    "resourceId",
    "venueId",
    "publicChannelId",
    "publicChannelHandle"
  ],
  "example": {
    "connectionId": "2fde64d5-54a3-47d0-800f-a015f92a8878",
    "resourceId": "d5b5eb29-9b8d-4d6f-8f4f-6f0e58f32568",
    "venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
    "publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
    "publicChannelHandle": "1.000"
  }
}
Full definition
{
  "type": "object",
  "properties": {
    "storefrontId": {
      "type": "string",
      "description": "Explicit venue storefront UUID in this brand directory.",
      "format": "uuid",
      "example": "26a6ca08-40bb-46b0-88cb-edd7b56e8643"
    },
    "venue": {
      "description": "Safe public profile for this actual venue.",
      "allOf": [
        {
          "$ref": "#/components/schemas/StorefrontPublicVenueProfileDto"
        }
      ],
      "example": {
        "venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
        "name": "Example name",
        "currency": "GEL",
        "timeZone": "Asia/Tbilisi",
        "countryCode": null,
        "city": null,
        "region": null
      }
    },
    "ordering": {
      "description": "Current attached active native preorder channel for this outlet and presentation connection, or null when none is available. This nonsecret discovery does not authorize an order or payment.",
      "nullable": true,
      "type": "object",
      "properties": {
        "connectionId": {
          "type": "string",
          "description": "Presentation connection UUID to retain as the nonsecret connection locator on native public draft requests. This does not replace current request-origin authorization.",
          "format": "uuid",
          "example": "2fde64d5-54a3-47d0-800f-a015f92a8878"
        },
        "resourceId": {
          "type": "string",
          "description": "Current attached PREORDER resource UUID within the presentation connection and selected venue. This is a discovery locator, not a capability.",
          "format": "uuid",
          "example": "d5b5eb29-9b8d-4d6f-8f4f-6f0e58f32568"
        },
        "venueId": {
          "type": "string",
          "description": "Actual native venue UUID owning this attachment and preorder channel. Orders remain scoped to this venue.",
          "format": "uuid",
          "example": "0604de3a-da74-4ad5-89f6-2dfe000d5391"
        },
        "publicChannelId": {
          "type": "string",
          "description": "Active native preorder public channel UUID belonging to the selected venue.",
          "format": "uuid",
          "example": "9bee613d-3322-4a03-8b9f-8a6259984eee"
        },
        "publicChannelHandle": {
          "type": "string",
          "description": "Native preorder channel discovery handle used by the public catalog. This is distinct from the enclosing storefront presentation handle.",
          "minLength": 1,
          "maxLength": 48,
          "example": "example"
        }
      },
      "required": [
        "connectionId",
        "resourceId",
        "venueId",
        "publicChannelId",
        "publicChannelHandle"
      ],
      "example": {
        "connectionId": "2fde64d5-54a3-47d0-800f-a015f92a8878",
        "resourceId": "d5b5eb29-9b8d-4d6f-8f4f-6f0e58f32568",
        "venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
        "publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
        "publicChannelHandle": "example"
      }
    },
    "reservations": {
      "description": "Current attached active native reservation channel for this outlet and presentation connection, or null when none is available. This nonsecret discovery grants no booking, waitlist, guest or financial authority.",
      "nullable": true,
      "type": "object",
      "properties": {
        "connectionId": {
          "type": "string",
          "description": "Presentation connection UUID used only as the nonsecret connection locator for native public reservation requests. This does not replace current request-origin authorization.",
          "format": "uuid",
          "example": "2fde64d5-54a3-47d0-800f-a015f92a8878"
        },
        "resourceId": {
          "type": "string",
          "description": "Current attached RESERVATION resource UUID within this presentation connection and venue. This is a discovery locator, not a capability.",
          "format": "uuid",
          "example": "d5b5eb29-9b8d-4d6f-8f4f-6f0e58f32568"
        },
        "venueId": {
          "type": "string",
          "description": "Actual native venue UUID owning this attachment and reservation channel. Booking and waitlist demand remain scoped to this venue.",
          "format": "uuid",
          "example": "0604de3a-da74-4ad5-89f6-2dfe000d5391"
        },
        "publicChannelId": {
          "type": "string",
          "description": "Active native reservation public channel UUID belonging to the selected venue.",
          "format": "uuid",
          "example": "9bee613d-3322-4a03-8b9f-8a6259984eee"
        },
        "publicChannelHandle": {
          "type": "string",
          "description": "Native reservation channel discovery handle used by public booking configuration and availability. This is distinct from the enclosing storefront presentation handle.",
          "minLength": 1,
          "maxLength": 48,
          "example": "1.000"
        }
      },
      "required": [
        "connectionId",
        "resourceId",
        "venueId",
        "publicChannelId",
        "publicChannelHandle"
      ],
      "example": {
        "connectionId": "2fde64d5-54a3-47d0-800f-a015f92a8878",
        "resourceId": "d5b5eb29-9b8d-4d6f-8f4f-6f0e58f32568",
        "venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
        "publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
        "publicChannelHandle": "1.000"
      }
    }
  },
  "description": "Public brand directory entry pairing an actual venue profile with its explicitly selected venue storefront identity.",
  "required": [
    "storefrontId",
    "venue",
    "ordering",
    "reservations"
  ],
  "example": {
    "storefrontId": "26a6ca08-40bb-46b0-88cb-edd7b56e8643",
    "venue": {
      "venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
      "name": "Example name",
      "currency": "GEL",
      "timeZone": "Asia/Tbilisi",
      "countryCode": null,
      "city": null,
      "region": null
    },
    "ordering": null,
    "reservations": null
  }
}
StorefrontPublicVenueProfileDto

Safe native venue display projection containing its identity, name, currency, time zone and nullable public geographic labels.

venueIdRequired

Actual native venue UUID.

string · uuid
Full definition
{
  "type": "string",
  "description": "Actual native venue UUID.",
  "format": "uuid",
  "example": "0604de3a-da74-4ad5-89f6-2dfe000d5391"
}
nameRequired

Public venue display name.

string
Full definition
{
  "type": "string",
  "description": "Public venue display name.",
  "minLength": 1,
  "maxLength": 255,
  "example": "Example name"
}
currencyRequired

Native venue currency code; presentation does not convert it.

string
Full definition
{
  "type": "string",
  "description": "Native venue currency code; presentation does not convert it.",
  "minLength": 3,
  "maxLength": 3,
  "example": "GEL"
}
timeZoneRequired

Native venue time-zone identifier.

string
Full definition
{
  "type": "string",
  "description": "Native venue time-zone identifier.",
  "minLength": 1,
  "maxLength": 64,
  "example": "Asia/Tbilisi"
}
countryCodeRequired

Configured venue country code, or null when unavailable.

string · null
Full definition
{
  "type": "string",
  "description": "Configured venue country code, or null when unavailable.",
  "nullable": true,
  "minLength": 2,
  "maxLength": 2,
  "example": "GE"
}
cityRequired

Public venue city, or null when unavailable.

string · null
Full definition
{
  "type": "string",
  "description": "Public venue city, or null when unavailable.",
  "nullable": true,
  "maxLength": 120,
  "example": "example"
}
regionRequired

Public venue region, or null when unavailable.

string · null
Full definition
{
  "type": "string",
  "description": "Public venue region, or null when unavailable.",
  "nullable": true,
  "maxLength": 120,
  "example": "example"
}
Full definition
{
  "type": "object",
  "properties": {
    "venueId": {
      "type": "string",
      "description": "Actual native venue UUID.",
      "format": "uuid",
      "example": "0604de3a-da74-4ad5-89f6-2dfe000d5391"
    },
    "name": {
      "type": "string",
      "description": "Public venue display name.",
      "minLength": 1,
      "maxLength": 255,
      "example": "Example name"
    },
    "currency": {
      "type": "string",
      "description": "Native venue currency code; presentation does not convert it.",
      "minLength": 3,
      "maxLength": 3,
      "example": "GEL"
    },
    "timeZone": {
      "type": "string",
      "description": "Native venue time-zone identifier.",
      "minLength": 1,
      "maxLength": 64,
      "example": "Asia/Tbilisi"
    },
    "countryCode": {
      "type": "string",
      "description": "Configured venue country code, or null when unavailable.",
      "nullable": true,
      "minLength": 2,
      "maxLength": 2,
      "example": "GE"
    },
    "city": {
      "type": "string",
      "description": "Public venue city, or null when unavailable.",
      "nullable": true,
      "maxLength": 120,
      "example": "example"
    },
    "region": {
      "type": "string",
      "description": "Public venue region, or null when unavailable.",
      "nullable": true,
      "maxLength": 120,
      "example": "example"
    }
  },
  "description": "Safe native venue display projection containing its identity, name, currency, time zone and nullable public geographic labels.",
  "required": [
    "venueId",
    "name",
    "currency",
    "timeZone",
    "countryCode",
    "city",
    "region"
  ],
  "example": {
    "venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
    "name": "Example name",
    "currency": "GEL",
    "timeZone": "Asia/Tbilisi",
    "countryCode": null,
    "city": null,
    "region": null
  }
}
TranslatedErrorDto

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

statusCodeRequired

HTTP status code repeated from the response.

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

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

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

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

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

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

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

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

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

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

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

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

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

Optional domain-specific blocker or validation details

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

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

fieldRequired

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

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

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

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

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

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

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

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

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

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

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

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

Hallify uses essential cookies and optional analytics.

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