Idempotency - Salty

Every POST endpoint accepts an Idempotency-Key header. If you send the same key + same body within 24 hours, the server returns the cached response instead of creating a duplicate.

Use it

curl -X POST $SALTY_API/people \
  -H "Authorization: Bearer $SALTY_API_KEY" \
  -H "Idempotency-Key: 9b1c-4f7e-…" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@acme.com"}'

Send it again with the same key — same response, no duplicate row.

What counts as “same”

Same workspace_id (auth) + same Idempotency-Key: lookup hit.
Same body (SHA-256 of the raw request body): cached response returned with the original status code.
Different body: 422 idempotency_key_mismatch. Don’t retry — pick a new key.

In-flight requests

If two requests with the same key arrive at the same time, the first proceeds and the second returns 409 idempotency_in_flight. Wait a moment and retry the second.

Lifetime

Rows live for 24 hours. After that the key is forgotten and a new request with the same key behaves like a first.

Key format

Anything up to 255 chars. UUIDs are conventional. Don’t reuse keys across logically different requests — they’re per-operation, not per-session.