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
heldUntilpasses. See Hold slots during checkout.
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:
10:07 to 10:52 blocks exactly 10:07–10:52.
The three supplier-time conflicts
All three are409, 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.
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.
Optimistic versioning on updates
Every booking, order, and order item DTO includes a numericversion:
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
- GET the resource again — you’ll see the new
versionand the current state. - 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.
- PATCH again.
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).
Which 409s are retryable
See Errors for the full envelope and code list.