> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomarketbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Error envelope, HTTP status codes, and what to do about them.

Every error response from the MarketBox API uses the same envelope.

## The envelope

```json theme={null}
{
  "code": "NOT_FOUND",
  "message": "Booking not found",
  "statusCode": 404,
  "requestId": "3f7c1a9e-5b2d-4e8a-9f01-2c6d8b4a7e13"
}
```

| Field | Meaning |
| - | - |
| `code` | Stable, machine-readable identifier. Use this for branching. |
| `message` | Human-readable explanation. May change over time. |
| `statusCode` | The same status as the HTTP response — included for clients that hide it. |
| `requestId` | Unique id for this request. Also returned in the `X-Request-Id` header. |

> [!TIP]
>
> Always log `requestId` alongside the request you made — it's what
> MarketBox support uses to look up a single call in our logs.

To correlate a call with your own logs, send your own id in an
`X-Request-Id` request header. If it is 128 characters or fewer, the API
uses it as the request's id: it comes back in the `X-Request-Id` response
header and as `requestId` in any error body. A longer value is ignored, and
the API generates a UUID instead. A request refused at the edge, before it
reaches the API (see [Authentication](https://docs.gomarketbox.com/concepts/authentication.md#when-the-key-is-missing-or-wrong)),
carries the gateway's own id instead.

### Conflict bodies carry extra fields

Supplier-time conflicts and hold-lifecycle failures use the same four envelope
fields as every other error — plus extras that tell you how to recover.

A **slot conflict** (`409 SLOT_HELD` / `SLOT_BOOKED`, from any booking or hold
route) adds `conflicts[]` and `hint`:

```json theme={null}
{
  "code": "SLOT_HELD",
  "message": "Supplier time is not available: HOLD resv_01kv8p2… (2026-07-15T14:00:00Z–15:00:00Z)",
  "statusCode": 409,
  "requestId": "9d4b6f21-8a3c-4f7e-b1d5-6e2a9c0f4b87",
  "conflicts": [
    {
      "claimType": "HOLD",
      "startUtc": "2026-07-15T14:00:00.000Z",
      "endUtc": "2026-07-15T15:00:00.000Z",
      "reservationId": "resv_01kv8p20m1gnqvxl92xln6awk8",
      "bookingId": null,
      "heldUntil": "2026-07-15T13:35:00.000Z",
      "supplierId": "sup_01kv60qge5eh59ap0gw0pqrrys"
    }
  ],
  "hint": "This time is held (reservation resv_01kv8p2…). Convert the hold via POST /v1/projects/{projectId}/holds/{reservationId}/convert, or release it…"
}
```

`conflicts[]` names **what** is blocking you (a `reservationId` for a `HOLD`, a
`bookingId` for a `BOOKING`) and **whose** calendar it blocks (`supplierId`,
`null` when unknown). `hint` names **what to do next**. Both are meant to be
read programmatically.

A **hold-lifecycle** failure (`409`, see the table below) is the plain envelope:

```json theme={null}
{
  "code": "HOLD_EXPIRED",
  "message": "Reservation resv_01kv8p2… expired at 2026-07-15T13:35:00.000Z",
  "statusCode": 409,
  "requestId": "5a1e8c34-2f6b-4d9a-8c17-3b5e7a1d9f42"
}
```

## Status codes

| Status | When you'll see it |
| - | - |
| `400` | The request is malformed: invalid JSON, invalid query parameters, a violated business invariant. |
| `401` | The user token on an end-user route (`/clients/me`, `/suppliers/me`) is missing, malformed, invalid or expired — sign the person in again. Also the beacon's publishable key, when it is missing or not live. A missing or unrecognised **API key** is `403`, not `401`. |
| `403` | The `x-api-key` header is missing or the key isn't recognised — rejected at the edge, before any scope check runs — or the key is valid but its `projectScope` does not allow the `{projectId}` in the URL, or it lacks the capability the route needs. On an end-user route, also: the signed-in person isn't an `ACTIVE` member of the project holding the route's permission. On the supplier plane, the `code` names which: `NOT_A_MEMBER`, `MEMBERSHIP_INACTIVE` or `NO_SUPPLIER_ROLE`. |
| `404` | The resource you targeted doesn't exist (or has been soft-deleted). On the supplier plane, also: the signed-in person has no supplier record to act on (`NO_SUPPLIER_ROLE` or `SUPPLIER_NOT_LINKED`). |
| `409` | Version conflict on an optimistic update, the supplier's time is already booked or held, capacity exceeded, duplicate registration, a credit that can't be booked (used up, expired, or on a cancelled order), or a card payment already in progress on the order. |
| `413` | The request body is too large — on the site-events routes, more than 256 KB per batch or 64 KB per beacon. Nothing was read. |
| `422` | The request is well-formed but asks for something the data cannot support: a package plan that no availability can fill, a line the service is not sold as, a service or offering that is no longer sold, a booking whose status no longer allows the change, or a credit treatment for a booking with no credit. Nothing was written. |
| `429` | Too many requests from this key. Today only the site-events routes rate-limit. Retry after the `Retry-After` header. |
| `503` | A dependency was down and nothing was recorded. Retry after the `Retry-After` header. |
| `5xx` | Something went wrong on our side. Safe to retry idempotent requests with backoff. |

## Common error codes

| `code` | Status | Notes |
| - | - | - |
| `VALIDATION_ERROR` | 400 | Request body or query failed schema validation. `message` names every failing field. See [Validation errors](#validation-errors). |
| `BAD_REQUEST` | 400 | Generic client-input failure covering several situations: an illegal status transition (e.g. nothing leaves `CANCELLED`; the `message` names the booking's current status), a mismatched currency between an order and an item you're adding to it, cancelling an `AWAITING_CONFIRMATION` booking with your key, a payment intent for an order that owes nothing, an unparseable pagination `cursor` (except on the supplier's alerts list, which answers `INVALID_CURSOR`), and other malformed input. `message` names the specific problem. |
| `HTTP_ERROR` | 400, 401 | A request refused before its route ran. `401` on an end-user route: a missing or malformed `Authorization` header, or a user token that is invalid or expired — sign in again. `400`: a body that isn't valid JSON. |
| `UNAUTHORIZED` | 401 | On an end-user route, a user token that names no user — and, once enforced, a token issued to another client. See [End-user authentication](https://docs.gomarketbox.com/concepts/end-user-authentication.md#where-the-user-token-comes-from). A missing or unrecognised **API key** is `FORBIDDEN`. |
| `FORBIDDEN` | 403 | API key is missing, isn't recognised, or cannot access this project. The first two are rejected at the edge before the request reaches the application, so `message` — not `code` — is what distinguishes them. On any end-user route, also "User account not found. Complete registration first." On the client plane (`/clients/me`), also "No active membership on this project" or "Insufficient permissions for this action"; the supplier plane answers those causes with `NOT_A_MEMBER`, `MEMBERSHIP_INACTIVE` or `NO_SUPPLIER_ROLE` instead. On `POST .../events`, a key without `events:write`. |
| `CAPABILITY_NOT_GRANTED` | 403 | Your API key lacks **Standard API access** (`*`): its capabilities are empty or name only site events. Checked before the project or the user token. A project admin grants it on the Application. See [Capabilities](https://docs.gomarketbox.com/concepts/authentication.md#capabilities). |
| `ACTING_ROLE_NOT_HELD` | 403 | An end-user request sent `X-MB-Acting-Role` naming a role the signed-in person doesn't hold. Drop the header. |
| `MEMBERSHIP_INACTIVE` | 403 | `POST .../clients/me` (onboarding) for a person whose access the business removed. Nothing was read or linked. The client asks the business to invite them again. See [Build a booking flow](https://docs.gomarketbox.com/guides/booking-flow-auth.md#onboard-the-client). On the supplier plane, "Your access to this project has ended.": the person's membership ended, with every role removed. |
| `NOT_A_MEMBER` | 403 | Supplier plane: "You are not a member of this project." The signed-in person has no membership of the project — for example, an invited supplier who hasn't accepted yet. See [Supplier portal: refusals](https://docs.gomarketbox.com/guides/supplier-portal-sign-in-and-access.md#refusals). |
| `NO_SUPPLIER_ROLE` | 403, 404 | Supplier plane: "You don't have supplier access on this project." The person is an `ACTIVE` member but acts under no `SUPPLIER` role: it was removed, or they never had it. `403` where their roles lack the route's permission, `404` where the permission passed but there is no supplier record to act on. Also `404` on the bookings routes for a request that sends `X-MB-Acting-Role: CLIENT`. See [When access ends](https://docs.gomarketbox.com/guides/supplier-portal-sign-in-and-access.md#when-access-ends). |
| `SUPPLIER_NOT_LINKED` | 404 | Supplier plane: "Your sign-in isn't linked to a supplier record on this project." The person holds `SUPPLIER`, but no single supplier record is linked to their sign-in. The business checks the supplier's invitation. |
| `FIELD_NOT_SELF_EDITABLE` | 403 | `PATCH .../suppliers/me` named a field only the business may change (`active`, `email`, `externalId`, `externalData`, `maxTravelTime`, `defaultLocale`). The whole body was refused. See [Supplier portal: profile and photo](https://docs.gomarketbox.com/guides/supplier-portal-profile-and-photo.md#edit-the-profile). |
| `START_END_LOCATIONS_DISABLED` | 422 | A supplier-plane schedule write set `startLocation`, `endLocation`, `driveTiming` or a `maxTravelOn…Drive` flag, and the project has start and end locations turned off: "Start and end locations are not enabled for this project, so startLocation cannot be set". Nothing was written. Sending `null`, or the value already stored, is never refused. Leave the field out. See [Supplier portal: availability](https://docs.gomarketbox.com/guides/supplier-portal-availability.md). |
| `SETTING_NOT_DELEGATED` | 422 | A supplier-plane schedule write set `driveTiming`, `maxTravelOnStartDrive` or `maxTravelOnEndDrive`, and the project hasn't let suppliers choose that setting: "driveTiming is set by the project and is not delegated to suppliers". Nothing was written. Hide the setting. |
| `INSIGHTS_DISABLED` | 403 | The project has switched off this supplier insight (demand, or search). Hide the insight in your portal. |
| `NOT_FOUND` | 404 | Resource doesn't exist or has been soft-deleted. Also returned for a `clientId` or `supplierId` in the request body that belongs to a different project — never a `403`, so a foreign id is indistinguishable from a missing one. |
| `UNRESOLVED_SUBDIVISION` | 400 | The address `state` isn't a recognised ISO 3166-2 subdivision of its country, and the offering or package prices by state or postal code there. `message` names the value and the subdivisions configured. Send the ISO code. See [Regional pricing](https://docs.gomarketbox.com/concepts/regional-pricing.md#country-and-state-codes). |
| `INVALID_ORDER_ITEM_REFERENCE` | 400 | `POST .../bookings`: the service line's `orderItemId` isn't an item of its `orderId`. Check both ids. |
| `REVIEW_ALREADY_EXISTS` | 409 | `POST .../bookings/{bookingId}/reviews`: the booking already has a review in that direction. Don't retry. |
| `INVALID_CURSOR` | 400 | `GET .../suppliers/me/alerts` only: the `cursor` isn't one this list issued, or came from another `filter`. Request the first page again without it. See [Supplier portal: insights and alerts](https://docs.gomarketbox.com/guides/supplier-portal-insights-and-alerts.md#alerts). |
| `VERSION_CONFLICT` | 409 | Concurrent modification — re-read the resource and try again. Also a stale `version` on a supplier's schedule, blocked time or travel zone, or another write landing on one during its `DELETE`. |
| `CONFLICT` | 409 | Generic write conflict covering situations like a booking that's already at capacity, or a client that's already registered as a participant on it (see [Group bookings and check-in](https://docs.gomarketbox.com/guides/group-bookings-and-check-in.md#register-a-participant)). Also an `ACTIVE` schedule that overlaps another `ACTIVE` one, and `DELETE .../suppliers/{supplierId}` when the supplier's sign-in changed during the delete — try again. Also a supplier photo confirmed or removed by another request while yours was saved, and `PUT .../suppliers/{supplierId}` when `active` changed between the update's read and its write: read the supplier again and retry. `message` names the specific problem. |
| `SLOT_BOOKED` | 409 | The supplier's time is already taken by a confirmed booking. `conflicts[]` names the `bookingId`. Not retryable — search availability again. |
| `SLOT_HELD` | 409 | The supplier's time is claimed by a live hold — often **your own**. `conflicts[]` names the `reservationId`; convert it instead of booking directly. See [Hold slots during checkout](https://docs.gomarketbox.com/guides/hold-slots-for-checkout.md#handling-a-held-slot). |
| `OCCUPANCY_CONTENTION` | 409 | Too many concurrent writes on one supplier's day; the internal retry gave up. **Retryable** — resend after a short backoff. On `POST .../holds/{reservationId}/release`, the hold is still `HELD` (it still expires on its own): retry the release. |
| `PAYMENT_IN_FLIGHT` | 409 | `POST .../orders/{orderId}/payment-intent` while a card payment on the order is already in progress (processing, or a saved-card charge). One open intent per order: "A card payment on order ord\_… is already in progress. Wait for it to finish, then read the order's transactions." Don't open another intent. Re-read the order's transactions. See [Accept payments with Stripe](https://docs.gomarketbox.com/guides/accept-payments-with-stripe.md). |
| `ORDER_NOT_DELETABLE` | 409 | `DELETE .../orders/{orderId}` on an order that holds a booking (booked or delivered) or a `PENDING` or `SUCCEEDED` payment or refund. `message` gives the counts. Nothing changed. Cancel the order with `POST .../orders/{orderId}/status` instead. See [Orders](https://docs.gomarketbox.com/resources/orders.md#the-order-lifecycle). |
| `OFFERING_NOT_PRICED` | 422 | The offering has no `DEFAULT` price rule, so nothing can be priced: "Offering has no DEFAULT price rule". Any write that prices it can return this: order create, adding an order item, booking create, hold convert and package bookings. The business adds a `DEFAULT` rule. Don't retry. |
| `NOT_A_PACKAGE_SERVICE` | 400 | `POST .../orders/{orderId}/package-bookings`, its client-plane twin, or converting a hold against a `PACKAGE` item, when the item's service has no active `PACKAGE` business model: "Service srv\_… has no active PACKAGE business model". The business turns one on. See [Packages](https://docs.gomarketbox.com/resources/packages.md). |
| `ORDER_ITEM_BUSINESS_MODEL_MISMATCH` | 400 | A booking line names a `businessModelType` its order item is not sold as, such as `PACKAGE` against a `SINGLE_SESSION` item. Send the kind the order item was sold as. See [Bookings](https://docs.gomarketbox.com/resources/bookings.md#creating-a-booking). |
| `TAX_MISMATCH` | 400 | You sent `tax` on `PATCH .../orders/{orderId}`, and it is not both the tax the lines compute and the tax the order stores — or the order has lines in a different currency. Nothing was written. Omit `tax`: the platform computes it. See [Orders](https://docs.gomarketbox.com/resources/orders.md#updating-an-order). |
| `ORDER_NOT_SETTLED` | 409 | You asked `POST .../orders/{orderId}/status` for `PAID`. An order becomes `PAID` only when its ledger covers its total. Record the payment instead of retrying. See [Orders](https://docs.gomarketbox.com/resources/orders.md#settling-an-order). |
| `TRANSACTION_IDEMPOTENCY_RECORD_MISSING` | 409 | An `idempotencyKey` matched an earlier recording whose row could not be read back. **Terminal** — do not retry. Re-read the order's transactions and contact support with the `requestId`. |
| `NO_SESSION_CREDIT` | 422 | `creditTreatment` was sent when cancelling a booking that holds no package credit. Nothing was cancelled. Resend without `creditTreatment`. |
| `NOT_SELLABLE` | 422 | A booking, order, order item or hold conversion names a service that isn't `LIVE` or was deleted, or an offering that isn't `ACTIVE`. `message` says which, for example "Service srv\_… is DRAFT and is not sold; only LIVE services take new bookings and orders". Nothing was written. A booking, hold conversion or package session against an order item already bought checks only the offering: the item stays bookable after its service stops being `LIVE`, but not after its offering stops being `ACTIVE`. Don't retry. Offer another service. |
| `PACKAGE_NOT_ACTIVE` | 422 | `POST .../orders`: a `PACKAGE` line names a package that is `DRAFT` or `ARCHIVED`. Nothing was written. Sell only `ACTIVE` packages. |
| `ORDER_NOT_PAYABLE` | 422 | `POST .../orders/{orderId}/transactions`: a `PAYMENT` or `COMP` on a `CANCELLED` order: "Order ord\_… is CANCELLED and cannot take a payment". A `REFUND` is still recorded. Don't retry. See [Record offline payments](https://docs.gomarketbox.com/guides/record-offline-payments.md). |
| `BOOKING_NOT_AMENDABLE` | 422 | `PATCH .../bookings/{bookingId}` changed the time or supplier of a booking that is no longer `SCHEDULED` or `STARTED`. Nothing was written. Other fields can still be edited. See [Bookings](https://docs.gomarketbox.com/resources/bookings.md). |
| `BOOKING_NOT_DELETABLE` | 422 | `DELETE .../bookings/{bookingId}` on a booking your key can't cancel: it took place or was settled (`AWAITING_CONFIRMATION`, `COMPLETED`, a no-show). Nothing changed. Settle it instead. See [Cancel or reschedule a booking](https://docs.gomarketbox.com/guides/cancel-or-reschedule-a-booking.md). |
| `BOOKING_NOT_OPEN_FOR_PARTICIPANTS` | 422 | Registering a participant on a booking that is no longer `SCHEDULED` or `STARTED`, or checking one in on a booking that is settled, disputed or cancelled. Nothing was written. See [Group bookings and check-in](https://docs.gomarketbox.com/guides/group-bookings-and-check-in.md). |
| `SERVICE_NOT_SOLD_AS` | 422 | An order line implies a rate the service does not actively sell, such as a `SINGLE_SESSION` line on a service with no active `SINGLE_BOOKING` rate. Nothing was written. See [Orders](https://docs.gomarketbox.com/resources/orders.md#creating-an-order). |
| `PAYLOAD_TOO_LARGE` | 413 | A site-events batch over 256 KB, or a beacon over 50 events or 64 KB. Nothing was read. Send fewer events per request. |
| `RATE_LIMITED` | 429 | More than about 50 site-events requests a second from this key (bursts of 100). Retry the same batch after `Retry-After`. |
| `SERVICE_UNAVAILABLE` | 503 | MarketBox couldn't check or record a site-events batch. Nothing was recorded. Retry the same batch after `Retry-After`. |
| `INTERNAL_ERROR` | 500 | An unexpected failure on our side. `message` is always "An unexpected error occurred". Quote the `requestId` to support. See [Retry guidance](#retry-guidance). |

The exact list of codes is also captured in
[`/v1/openapi.json`](https://docs.gomarketbox.com/api-reference/introduction). New codes may be added
over time; treat unknown codes as the generic class implied by the HTTP
status.

## Hold and slate codes

These come from the hold endpoints (`POST /holds`, `/holds/{reservationId}/convert`)
and the slate-based booking routes. Full walkthrough in
[Hold slots during checkout](https://docs.gomarketbox.com/guides/hold-slots-for-checkout.md#troubleshooting).

| `code` | Status | What it means | What to do |
| - | - | - | - |
| `MISSING_BOOKING_TZ` | 400 | The held interval carries no `bookingTz` and no location to derive one from. | Send `bookingTz` (IANA, e.g. `America/Toronto`) on every entry in `intervals[]`. It is required. |
| `UNSUPPORTED_SKU_TYPE` | 400 | The order item you're converting against is a `SUBSCRIPTION`, `MEMBERSHIP`, or `DEPOSIT`. | Convert against a `PACKAGE` or `SINGLE_SESSION` item. Nothing is wrong with the hold. |
| `INVALID_ORDER_REFERENCE` | 400 | The `orderId` doesn't exist in this project. | Check the id and the project. |
| `HOLD_EXPIRED` | 409 | You converted after `heldUntil`. Expiry is lazy — the hold simply stopped blocking anyone. | Re-hold the time and convert sooner. Someone else may have taken it. |
| `RESERVATION_NOT_FOUND` | 409 | No such `reservationId` in this project. (`GET /holds/{id}` returns `404 NOT_FOUND` instead.) | Don't retry. Place a new hold. |
| `RESERVATION_NOT_HELD` | 409 | The hold is already `CONVERTED` or `RELEASED`. | If `CONVERTED`, re-read the hold — your bookings already exist. Converting is idempotent, not repeatable. |
| `RESERVATION_FORBIDDEN` | 409 | The `heldBy` you sent doesn't match the hold's owner. | Send the same `heldBy` used to create the hold (typically your checkout session id). |
| `RESERVATION_MULTI_INTERVAL` | 409 | You converted a multi-interval hold against a `SINGLE_SESSION` order item. | Use a `PACKAGE` order item, or hold exactly one interval. |
| `SLATE_NOT_FOUND` | 409 | The `slateId` no longer exists. | Re-run `POST /availability/package-slate` and hold the fresh slate. |
| `SLOT_NOT_FOUND` | 409 | One or more `slotIds` no longer exist. | Same — regenerate the slate. |
| `EMPTY_SLATE` | 409 | The slate resolved to zero slots, or you sent none of `intervals` / `slateId` / `slotIds`. | Send exactly one of the three. |
| `SUGGESTION_EXPIRED` | 409 | The underlying suggestion aged out before you booked it. | Re-run availability. |
| `SLOT_NOT_BOOKABLE` | 409 | The slot resolved but can no longer be booked. | Re-run availability. |
| `LOCATION_UNRESOLVABLE` | 409 | No supplier travel zone covers the requested coordinates. | The supplier doesn't serve that address. Pick another supplier or location. |
| `SLOT_NO_LONGER_BOOKABLE` | 409 | `POST .../package-bookings` by `slateId` or `slotIds`: the slate went stale before you booked it. The body adds `freshSuggestions`, re-planned for the same credit. | Show `freshSuggestions` and book from them. Nothing was booked. |
| `NO_COMPLETE_SLATE` | 422 | `POST /availability/package-slate`: no plan fills the package, and there is no partial slate or alternative cadence to offer. `message` gives the reason. | Change the `rrule`, the dates or the location, and plan again. |
| `NO_AVAILABILITY` | 422 | `POST /availability/package-slate`: no supplier has any availability for the request. | Try another location or date range. |
| `SLOT_TIME_UNAVAILABLE` | 409 | `POST /suggestions/slots/{slotId}/reschedule`: the supplier doesn't work then, or the time overlaps a booking or blocked time. | Pick another time. The slate is unchanged. |
| `SLOT_NO_LONGER_FREE` | 409 | `POST /suggestions/slots/{slotId}/reschedule`: a concurrent hold took the slot while you moved it. | Retry once at a different time. |

> [!WARNING]
>
> A `404 NOT_FOUND` with the message **`Location stz_… not found`** on convert
> is not a missing record — it means the hold carried a travel-zone id
> (`stz_…`) under `locationType: "PHYSICAL"` (or with no `locationType` at
> all), so it was looked up in the wrong table. Re-hold with
> `locationType: "TRAVEL_ZONE"` plus `latitude`, `longitude`, and `address`.
> See [Hold slots during checkout](https://docs.gomarketbox.com/guides/hold-slots-for-checkout.md#a-travel-zone-checkout-end-to-end).

## Package credit codes

These come from the routes that plan or book from an order's credits:
`POST /availability/package-slate` with `orderId` + `orderItemId`,
`POST /orders/{orderId}/package-bookings`,
`POST /clients/me/orders/{orderId}/package-bookings`, `POST /bookings` and
`POST /holds/{reservationId}/convert`. Full walkthrough in
[Create a package booking](https://docs.gomarketbox.com/guides/create-a-package-booking.md#what-a-booking-call-checks).

| `code` | Status | What it means | What to do |
| - | - | - | - |
| `ORDER_ITEM_SERVICE_MISMATCH` | 400 | A session or booking line names a service or offering other than the order item's. A credit books only its own offering. | Book the item's own `serviceId` and `offeringId`. Plan the slate from that package or from the credit. |
| `ORDER_ITEM_QUANTITY_UNAVAILABLE` | 400, 409 | `400`: you asked for more sessions than the item has left, and nothing was booked. `409`: a concurrent booking used the credits after the check passed. On `package-slate`, `409`: the credit has no sessions left to plan. | Re-read `quantityRemaining` and book only what is left. |
| `PACKAGE_EXPIRED` | 409 | A session starts after the order item's `expiresAt`. On `package-slate`, the credit has already expired. | Book before the expiry. An expired credit can't be planned or booked. |
| `NOT_A_PACKAGE_ITEM` | 400 | The `orderItemId` isn't a `PACKAGE` line. | Pass the order's `PACKAGE` item. |
| `IDEMPOTENCY_KEY_CONFLICT` | 409 | The `idempotencyKey` was already used with a different body. | Use a fresh key for each new attempt. The same key with the same body replays the first `201`. |
| `ORDER_CANCELLED` | 409 | The order is `CANCELLED`. Its sessions were cancelled and its credits released. Also refused when converting a hold that already converted. | Don't retry. Create a new order. |
| `PACKAGE_SLATE_TOO_LARGE_FOR_ATOMIC` | 422 | `atomicity: "all_or_nothing"` (the default) books at most 15 sessions in one call. Nothing was booked. | Book fewer sessions per call (for example with `slotIds`), or send `atomicity: "best_effort"` if your project allows it. |
| `BEST_EFFORT_NOT_ENABLED` | 422 | You sent `atomicity: "best_effort"`, and your project doesn't allow partial package booking. Nothing was booked. | Use the default `all_or_nothing`, in calls of 15 sessions or fewer. |
| `CREDIT_NOT_BOOKABLE` | 409 | `POST /clients/me/orders/{orderId}/package-bookings` only: the credit isn't one `GET /clients/me/credits` would list — the order isn't `PAID`, or the credit is used up, expired or removed. | Re-read the client's credits and offer only those listed. See [Book a client's package credit](https://docs.gomarketbox.com/guides/book-a-package-credit.md#what-the-booking-call-checks). |

A cancelled order comes back as:

```json theme={null}
{
  "code": "ORDER_CANCELLED",
  "message": "Order ord_01kx16f0a1c7b2sd91xzq3mn5p is CANCELLED",
  "statusCode": 409,
  "requestId": "8a3c6e25-1f9d-4b72-9e40-5d2b8c1a7f63"
}
```

## Supplier booking codes

These come from the supplier plane's booking routes: cancel, reschedule and the
attendance report. Full walkthrough in
[Supplier portal: bookings](https://docs.gomarketbox.com/guides/supplier-portal-bookings.md#when-a-change-is-refused).

| `code` | Status | What it means | What to do |
| - | - | - | - |
| `PARTICIPANT_ACTION_DISABLED` | 403 | The booking's service doesn't let suppliers cancel (or reschedule). | Hide the action. The supplier contacts the business. |
| `BOOKING_NOT_SCHEDULED` | 409 | The booking is no longer `SCHEDULED`. | Re-read the booking. Don't retry. |
| `NOTICE_WINDOW_PASSED` | 409 | Too close to the start to change it. | Don't retry. The supplier contacts the business. |
| `NEW_START_INSIDE_NOTICE_WINDOW` | 422 | Reschedule only: the new time is itself inside the notice window. | Pick a later time. |
| `SLOT_UNAVAILABLE` | 409 | Reschedule only: the new time is outside working hours, in blocked time or overlaps another booking. | Pick another time. |
| `SLOT_UNVERIFIABLE` | 409 | Reschedule only: availability couldn't be checked, so nothing changed. | Try again later, or contact the business. |
| `REPORT_ALREADY_EXISTS` | 409 | A different attendance answer is already on file. | Show the answer on file. Don't retry. |
| `BOOKING_ALREADY_SETTLED` | 409 | The booking is already settled. | Don't retry. |
| `BOOKING_NOT_REPORTABLE` | 422 | The booking is cancelled or hasn't ended yet, or (a `SUPPLIER` report) is already settled. Also answered by `POST .../bookings/{bookingId}/reports` with your key. Nothing was written. | Report after the booking ends. Don't retry a settled one. |

## Validation errors

A request that fails schema validation is a `400 VALIDATION_ERROR`. The
`message` lists **every** failing field, not just the first. Each issue is
the dot-joined field path, a colon and the reason, and issues are separated
by `; `:

```json theme={null}
{
  "code": "VALIDATION_ERROR",
  "message": "sessions.0.latitude: latitude and longitude are required for TRAVEL_ZONE; sessions.0.address: address is required for TRAVEL_ZONE",
  "statusCode": 400,
  "requestId": "7c3f0a5d-9b2e-4a68-9d14-5f8c2b6e0a91"
}
```

There is no nested errors array and no separate `path` field — the paths
are inside `message`. To show each problem separately, split `message` on
`; `, then split each part on its first `: `.

A rule the route checks after the schema passes is a `400 BAD_REQUEST`
instead, with one problem per response:

```json theme={null}
{
  "code": "BAD_REQUEST",
  "message": "bookingEndUtc must be strictly after bookingStartUtc",
  "statusCode": 400,
  "requestId": "e2a7c9b4-1f6d-4083-9c5e-8b3a0d7f2e16"
}
```

## Retry guidance

* **`4xx`** — never retry blindly. Fix the request and try again.
* **`409 VERSION_CONFLICT`** — re-read the resource (its `version` field
  has advanced), reapply your patch, and retry.
* **`409 OCCUPANCY_CONTENTION`** — transient contention on a supplier's
  day. Resend the same request with a short, jittered backoff.
* **`409 SLOT_HELD` / `SLOT_BOOKED`** — never retry the same call. The
  response body names the blocking `reservationId` or `bookingId`; convert
  the hold, or pick a different time. See
  [Concurrency](https://docs.gomarketbox.com/concepts/concurrency.md).
* **`409 HOLD_EXPIRED` / `RESERVATION_*`** — never retry. The hold is in a
  terminal state, and retrying cannot move it out of one. Re-hold, or (for
  `RESERVATION_NOT_HELD` on an already-`CONVERTED` hold) re-read it — your
  bookings already exist.
* **`5xx`** — retry idempotent requests (`GET`, `DELETE`, `PATCH` with
  the same body, status changes to the same target) with exponential
  backoff. Avoid blind retries on `POST`, since the original may have
  succeeded.
* **`429 RATE_LIMITED`** and **`503 SERVICE_UNAVAILABLE`** — wait for the
  `Retry-After` header, then resend the same request. On the site-events routes,
  resend the same batch with the same `eventId`s; nothing is counted twice.

## Surfacing errors to support

When opening a support ticket, include:

1. The `requestId` from the failed call.
2. The approximate time (with timezone).
3. The endpoint and HTTP method.
4. The `code` and `message` from the response.

That's enough for MarketBox support to find the exact request in our
logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.