Skip to main content
Two things in this API can race, and they are guarded differently. A supplier’s time is exclusive. Two bookings can’t overlap on the same supplier, and every write that claims supplier time — a booking, a package booking, a hold, a reschedule, a hold conversion — passes through an occupancy guard that enforces it transactionally. If two callers race for the same time, exactly one wins; the other gets a 409 naming what blocked it. (The guard is on for every project by default; see When the guard is off for the one exception.) Everything else is optimistic. Mutable resources (bookings, orders, order items) carry a numeric version that advances on every write. If two writers race on the same record, one wins and the other gets 409 VERSION_CONFLICT.

Supplier-time exclusivity

Time on a supplier’s calendar can be claimed by exactly one of two things:
  • a booking — blocks that time permanently (until cancelled);
  • a hold — blocks that time until its heldUntil passes. See Hold slots during checkout.
The guard runs inside the same transaction as the booking write, so there is no window between “we checked” and “we wrote”. Two concurrent POST /bookings for the same supplier at the same instant produce exactly one booking and one 409 — never two bookings (unless the guard is off for your project), and never a half-written package.
The guard enforces hard interval exclusivity only. Travel buffers, travel-time clashes, and working hours are enforced by the availability engine on the read side, when you search. The write guard is the safety net underneath: it is what makes a physically impossible schedule unrepresentable, even if you book by hand without searching first.

When the guard is off

A project setting, suggestionConfig.enforceOccupancyGuard, can switch the guard off. It defaults to true. It is set in the project’s settings, and the public API can’t read or change it. With the guard off, POST /bookings and POST .../package-bookings write bookings without checking or claiming supplier time. They never return SLOT_BOOKED or SLOT_HELD, and two of them can overlap. Holds, hold conversions and reschedules still check. If you see overlapping bookings on one supplier, check whether the setting is off for your project.

Intervals are half-open

An interval is [startUtc, endUtc) — the start is inclusive, the end is exclusive. Back-to-back bookings do not collide. A session ending at 15:00:00Z and one starting at 15:00:00Z are both bookable on the same supplier:
Times are arbitrary minute precision — there is no 15-minute grid. A booking from 10:07 to 10:52 blocks exactly 10:07–10:52.

The three supplier-time conflicts

All three are 409, and all three tell you exactly what is in the way.

SLOT_BOOKED

A confirmed booking already occupies the time. conflicts[] names the blocking bookingId.
Not retryable — the time is gone. Search availability again and offer something else.

SLOT_HELD

A live hold occupies the time, and conflicts[] names the blocking reservationId plus the heldUntil at which it lapses. Most often, the hold is your own: you held the time for a checkout and then called POST /bookings (or POST .../package-bookings) directly. The direct booking routes never consume a hold — if you hold, you convert. Take the reservationId out of the response and call POST /holds/{reservationId}/convert instead. If the hold belongs to someone else’s checkout, heldUntil tells you when the time frees up. The full body and both branches are in Hold slots during checkout.

OCCUPANCY_CONTENTION

Not a conflict over your time — a conflict over the row. Claims are guarded per supplier per UTC day with an optimistic version, and several writers hammering the same supplier-day serialize. The API retries internally; OCCUPANCY_CONTENTION means even the bounded retry gave up. This one is retryable. Re-send the same request after a short backoff (50–200 ms, jittered). On a hold release, the hold is still HELD after this 409, so retry the release. Two people booking different times with the same supplier on the same day normally both succeed — you should see this code only under genuinely heavy contention.
Holds also block search. A held slot is not returned as available by /availability/search or /availability/package-slate while its hold is live. A slot that disappears between two searches may simply be mid-checkout for someone else — it will come back if their hold lapses.

Optimistic versioning on updates

Every booking, order, and order item DTO includes a numeric version:
You don’t have to track it manually — the server reads the current version on each PATCH/DELETE and applies your update atomically. But you’ll see it move when something changes, and you’ll get 409 VERSION_CONFLICT when two writers race, or when you read, sat on the result, and then patched a record that had since advanced.

Recovering

  1. GET the resource again — you’ll see the new version and the current state.
  2. Reapply your change on top of the fresh state. If the new state makes your update irrelevant (someone else already cancelled the booking you were about to cancel), skip the retry.
  3. PATCH again.
Note that a reschedule passes through the occupancy guard as well as the version check: moving a booking onto time that someone else holds or has booked returns SLOT_HELD / SLOT_BOOKED, not VERSION_CONFLICT.

Where you’ll see 409

Capacity and duplicate conflicts

409 also covers business-level conflicts that are neither version-based nor supplier-time-based — both return the generic CONFLICT code:
  • Booking at capacity — registering a participant would put the booking past its capacity. The booking’s version is unchanged.
  • Duplicate participant — the client is already on the participant list (and not in a cancelled state).
These aren’t fixable by re-reading and retrying — the action just can’t proceed. Surface them to the user rather than looping.

Which 409s are retryable

See Errors for the full envelope and code list.