Errors

A request that fails answers with an HTTP status and a problem details body (RFC 9457), with the content type application/problem+json:

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "booking.slot_taken",
  "detail": "The table is booked at that time.",
  "requestId": "3f2a9c01d4e5b6a7"
}

Field
`status`	The HTTP status, repeated.
`title`	The HTTP status text.
`code`	A stable, machine-readable code. Branch on this.
`detail`	What went wrong, for people. It may change at any time, so don't parse it.
`errors`	For validation failures: one entry per field, `{location, message, value}`, where `location` is like `body.contact.phone`.
`requestId`	The same as the `X-Request-ID` header. Quote it when you contact us.

Codes are only ever added, never changed or reused. Treat a code you don't know by its HTTP status.

What to do with each status#

Status	Meaning	What to do
`400`	The request is malformed.	Fix the request; don't retry as it is.
`401`	No credential, or it is wrong, revoked, expired or for the other environment.	Check the key; refresh an OAuth token.
`403`	The credential is good but can't do this.	See the code: a missing scope, the plan, Developer access.
`404`	No such object, or the credential doesn't cover the venue.	Don't retry.
`409`	The request clashes with the current state.	Read the object again, then decide.
`413` / `415`	The body is too big, or isn't JSON.	Fix the request.
`422`	The request is well formed but its values are refused.	See `errors` and the code.
`429`	Too many requests.	Wait `Retry-After` seconds.
`5xx`	Something failed on our side.	Retry with backoff and the same `Idempotency-Key`.

Codes#

Authentication and access#

Status	Code	When
401	`auth.key_invalid`	The key or token is missing, unknown, revoked or expired, or belongs to the other environment.
403	`auth.scope_missing`	The credential lacks the scope the endpoint needs (`detail` names it).
403	`auth.plan_feature`	The venue's plan doesn't include the feature this scope needs.
403	`auth.developer_access_off`	Boozie has turned the venue's Developer access off.
403	`auth.host_key_required`	`/hosts/me…` with a venue key that holds `hosts:read` but isn't bound to a host. (Org keys and OAuth tokens can't hold `hosts:read`, so they get `auth.scope_missing`.)
429	`rate_limited`	Over the rate limit. See `Retry-After`.

Requests#

Status	Code	When
400 / 422	`invalid_request`	The body or a parameter fails validation: a missing or unknown field, a wrong type, a value out of range. See `errors`.
400	`cursor.invalid`	The `after` cursor isn't one we gave you.
400	`idempotency.key_missing`	A `POST` without an `Idempotency-Key` (or one over 255 characters).
409	`idempotency.in_progress`	The first request with this key is still running. Retry after `Retry-After`.
422	`idempotency.mismatch`	This key was used with a different request.
404	`not_found`	No such object, or a venue the credential doesn't cover.
404	`route_not_found`	No such endpoint. Check the path against the reference.
409	`conflict`	A conflict without a more specific code.
500	`internal`	Our fault. Retry; if it keeps happening, contact us with the `requestId`.
503	`unavailable`	A part of the API isn't set up on this environment, such as `GET /oauth/authorize` without a consent page. Try later.

Bookings#

Status	Code	When
422	`validation.time`	`startsAt`/`endsAt` are missing, the wrong way round or more than 24 hours apart.
422	`validation.pax`	The number of guests is out of range (1–200) or doesn't suit the table.
422	`validation.table`	`tableId` isn't one of the venue's tables.
422	`validation.date`	A `date` that isn't a real day, has passed or is too far ahead.
422	`validation.customer`	Send either `customerId` or `contact`; or the customer isn't the venue's.
422	`validation.name` / `validation.phone` / `validation.email`	The contact's details are refused. Phones are E.164, such as `+60123456789`.
422 / 400	`booking.outside_hours`	The time isn't within one of the venue's sessions. Use availability.
409	`booking.venue_not_bookable`	The venue doesn't take bookings now.
409	`booking.slot_taken`	The table, or the customer, already has a booking at that time.
409	`booking.transition_not_allowed`	The booking's status doesn't allow this, e.g. confirming a cancelled booking.
409	`booking.not_editable`	The booking has started, or isn't pending or confirmed.
409	`booking.arrival_window`	Too early or too late to mark the arrival.

Guest list#

Status	Code	When
409	`guestlist.not_running`	The venue doesn't run a guest list on Boozie.
409	`guestlist.closed`	The list for that night is closed (past its cut-off, or not running that night).
409	`guestlist.full`	The list for that night is full.
409	`guestlist.already_listed`	They're on the list for that night already.
422	`validation.guest`	The guest's details are refused.

Webhooks#

Status	Code	When
400	`webhook.url_invalid`	The URL isn't `https://` with a public hostname. See the URL rules.
400	`webhook.events_invalid`	An unknown event, or one whose read scope the credential lacks.
409	`webhook.too_many`	The venue has 10 endpoints already.
409	`webhook.endpoint_disabled`	The endpoint is off; turn it on first.
409	`webhook.not_replayable`	That delivery can't be replayed.
503	`webhook.not_configured`	Webhooks aren't set up on this environment yet.

Sandbox#

Status	Code	When
404	`sandbox.unavailable`	There is no sandbox on this environment. Boozie turns it on per environment, never on production.
422	`invalid_request`	`POST /sandbox/keys` without a real email address, or with a name over 60 characters.
429	`rate_limited`	Too many key requests from this IP address (10 a day) or in all (200 a day). See `Retry-After`.
503	`sandbox.not_ready`	The sandbox isn't set up on this environment yet. Try again later.

The OAuth token and revoke endpoints answer in RFC 6749's own format instead. See OAuth apps.