Idempotency

Retry writes safely with the Idempotency-Key header.

1 min read

Networks fail in the middle of requests. If a POST times out, you cannot tell whether the campaign was created. An idempotency key makes the retry safe: the API runs the write once and replays the stored response for every repeat.

Sending a key#

Add an Idempotency-Key header (up to 255 characters) to any POST, PATCH, PUT or DELETE. Use a value that is unique per operation, such as a UUID or your own record id.

curl

curl https://api.listener.com/v1/campaigns \
  -H "Authorization: Bearer $LISTENER_API_KEY" \
  -H "Idempotency-Key: io-2026-0142" \
  -H "Content-Type: application/json" \
  -d '{"title": "Acme Coffee Q4 host reads", "brand": "Acme Coffee"}'

What happens on a repeat#

Situation	Result
Same key, same body, first request finished	The stored response is returned with `Idempotent-Replayed: true`. Nothing is written again.
Same key, first request still running	`409 idempotency_key_in_use`. Wait and retry.
Same key, different body	`400 idempotency_key_reused`. Use a new key for a new operation.
Key older than 24 hours	Treated as new.

Keys are scoped to the credential that sent them, so two API keys or two OAuth connections never collide. Responses are stored whatever their status, including errors, so a retry of a request that failed validation fails the same way.

Good practice#

Generate the key before the first attempt and reuse it for every retry of that operation.
Derive it from your own data when you can (invoice-842-create), so a crash-and-restart also replays instead of duplicating.
Retry with backoff on network errors, 429 and 5xx. See Errors.