Skip to main content
Every error response from the MarketBox API uses the same envelope.

The envelope

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), 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:
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:

Status codes

Common error codes

The exact list of codes is also captured in /v1/openapi.json. 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.
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.

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. A cancelled order comes back as:

Supplier booking codes

These come from the supplier plane’s booking routes: cancel, reschedule and the attendance report. Full walkthrough in Supplier portal: bookings.

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 ; :
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:

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.
  • 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 eventIds; 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.