A booking retry must reuse the identity of the original booking attempt. Generating a new key whenever the assistant calls the tool defeats duplicate protection precisely when a response is lost.
Idempotency identifies a business operation
An idempotency key lets a backend recognise repeated attempts to perform the same logical operation. It should be scoped to the tenant, action type, and confirmed booking intent. Keep it opaque and avoid placing caller details inside it.
In a proposed design, the application creates the key after the caller confirms the booking details. The backend stores the key, a fingerprint of the accepted payload, operation state, and the authoritative result. A uniqueness constraint or equivalent atomic mechanism prevents concurrent requests from both creating appointments.
The key is not a substitute for checking appointment availability. Two different callers can legitimately generate different keys for the same remaining slot. Capacity constraints must still be enforced by the booking system.
Test the response-loss window
A fictional caller confirms Tuesday at 10:00. The booking service creates appointment A-17, but the network drops before the agent receives the response. On retry, the same operation key and payload should return A-17 rather than create A-18.
If the caller then changes to Wednesday, that is a new confirmed operation. Reusing the old key with altered details should produce a conflict, not silently return Tuesday’s appointment. Whether the old appointment needs cancellation is a separate workflow decision.
| Request sequence | Expected result |
|---|---|
| Same key, same details, sequential retries | Same booking reference |
| Same key, same details, concurrent requests | One booking creation |
| Same key, different date | Explicit payload conflict |
| New key, already occupied slot | Availability rule still enforced |
Use a fixture that drops the response after the write commits. A test that fails the request before execution does not exercise the dangerous uncertainty window.
Expiry and external systems need explicit policy
Retain operation records long enough to cover supported retries and delayed job execution. After expiry, a repeated request might execute again. Reconcile known booking references before reviving very old operations.
An internal idempotency ledger cannot guarantee uniqueness in an external service if the external write succeeds but its reference is lost. Use that service’s supported operation identity or a reliable reconciliation path. Stripe’s idempotency documentation is a useful concrete example of service-specific replay semantics; it does not establish the behaviour of a calendar API.
The voice integration case study describes related tool work. This booking design is proposed. Pair it with safe tool retries.
Booking idempotency FAQ
Can the call identifier be the only key?
Usually not. One call may include several distinct bookings or a corrected booking intent.
Should a retry receive a new key?
No. Preserve the original key when retrying the same confirmed operation.
Does idempotency guarantee exactly one appointment forever?
No. Its guarantees depend on storage, concurrency, retention, and the behaviour of the authoritative booking service.