Idempotency and retries

Retry safely with an Idempotency-Key, backoff, and Retry-After.

Networks fail. Retry safely:

• Send an Idempotency-Key header (a UUID) with every POST /v1/events. If we’ve seen the key in the last 24 hours, we return the first response and record nothing new.
• Reuse the same key when you retry the same batch. A new batch gets a new key.
• Retry on network errors, 429, and 5xx, with exponential backoff and jitter. Honor Retry-After when it’s present.
• Don’t retry 400 or 401: fix the request.

Background: idempotence, and the IETF’s Idempotency-Key header draft, which our header follows.

Links on this page

• https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After
• https://en.wikipedia.org/wiki/Idempotence
• https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/