Idempotency
Send an Idempotency-Key on creating requests so a retry can never create a second RSVP or event.
Networks fail. If you send a request and never hear back, you cannot tell whether it ran. An Idempotency-Key makes the retry safe: the second request returns the first one's answer instead of doing the work again.
curl -X POST https://api.whocoming.com/v1/events/evt_demo0000000000000001/rsvps \
-H "Authorization: Bearer wc_test_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c2a9e-1b7d-4c55-9b0e-3c1d2e4f5a6b" \
-d '{"name":"Ada Lovelace","email":"ada@example.com"}'Where it works
The creating requests:
POST /v1/eventsPOST /v1/seriesPOST /v1/events/{id}/rsvpsPOST /v1/webhook-endpointsPOST /v1/public/events/{id}/rsvps(the public RSVP form; the widget sends a key with every submission)
The rules
- The key is any 1 to 255 printable ASCII characters. A fresh UUID per logical operation is the usual choice. Reuse it only for retries of that same operation.
- A replay (same key, same method, path and body) within 24 hours gets the original status and body back, with the header
Idempotent-Replayed: true. Nothing runs twice. - The same key with a different request answers
409 idempotency_conflict, before anything is created. Body comparison ignores key order and whitespace in JSON. In particular, reusing a key for another guest never returns the first guest's RSVP. - While the first request is still running, a duplicate answers
409 idempotency_conflict. Retry a moment later and you get the replay. - Errors you can retry are not stored. A
5xxor429frees the key, so your retry with the same key actually runs. - Keys are separate per organization and per mode, so a test key and a live key never collide.
On the public RSVP endpoint
POST /v1/public/events/{id}/rsvps needs no API key, so its keys are kept per event's organization and mode instead. The rules above apply, with two differences:
turnstile_tokenis left out when comparing bodies, because a bot-check token works only once and a retry fetches a new one. A replay does not run the bot check again.- Only a successful
201is stored. Any error frees the key, so the guest can fix the form and send again with the same key.
A key is also tied to the guest's email: the same key with another email is a different request (409 idempotency_conflict), never the first guest's RSVP or manage link.
And on top of that
RSVPs are also protected by a rule in the database: one RSVP per email per event. Even without a key, a duplicate RSVP for the same email answers 409 already_registered rather than creating a second one.
The SDK takes an idempotencyKey option and retries 429 and 5xx responses with backoff, reusing the same key.