Skip to content
TapLogic API
Italiano

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

  1. Add Idempotency-Key to every POST, PATCH and DELETE: one unique value per operation, for example a v4 UUID (at most 255 characters).
  2. The first request runs and its response is stored for 24 hours, bound to the API key.
  3. A repeat with the same key and body returns the same response, with the Idempotent-Replayed: true header. No new effect.
  4. 4xx errors are stored and replayed too: fix the request and use a new key.
  5. 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.