Skip to Content

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/events
  • POST /v1/series
  • POST /v1/events/{id}/rsvps
  • POST /v1/webhook-endpoints
  • POST /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 5xx or 429 frees 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_token is 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 201 is 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.

On this page