Idempotency
A network that fails halfway must not create two endpoints or two invitations. With Idempotency-Key you repeat the same write without double effects.
curl -X POST "https://api.taplogic.it/v1/members" \
-H "Authorization: Bearer $TAPLOGIC_API_KEY" \
-H "Idempotency-Key: 2f1c6a8e-7b0d-4b8e-9f51-3a2c9d4e7f10" \
-H "Content-Type: application/json" \
-d '{"email":"giulia.rossi@esempio.it","role":"member"}'How it works
- Add Idempotency-Key to every POST, PATCH and DELETE: one unique value per operation, for example a v4 UUID (at most 255 characters).
- The first request runs and its response is stored for 24 hours, bound to the API key.
- A repeat with the same key and body returns the same response, with the Idempotent-Replayed: true header. No new effect.
- 4xx errors are stored and replayed too: fix the request and use a new key.
- 5xx errors are not stored: repeat with the same key.
Conflicts
- 422 idempotency_key_mismatch: same key, different body or path. It is almost always a bug in the code.
- 409 idempotency_in_progress: the first request is still running. Wait a moment and repeat.
- 409 idempotency_replay_unavailable: the saved response can no longer be read. Check the state of the resource and use a new key.
After 24 hours the key expires and a request with the same value runs again.