Idempotency

Every write carries an Idempotency-Key, so retrying a request after a timeout never records something twice.

The header

Send a unique key with every POST, PUT and PATCH. A UUID works well. The token endpoint is the only write that doesn't need one.

Idempotency-Key: 7f3c9e2a-41d8-4a6e-9b0e-2c5d8a1f6b30

A write without a key, with a blank key, or with a key longer than 255 characters gets 400.

Retrying

• Repeat a request with the same key when you don't know whether it worked. If it already succeeded, you get the original response back and nothing runs again.
• Use a new key for a new operation, even if the body is the same.
• A key belongs to the request it was first sent with. Sent again with another body, or to another endpoint, it gets 422 with "code": "idempotency_key_reused", and nothing runs. The order of keys and the spacing in a JSON body don't count.
• If the first request with a key is still running, a second one with that key gets 409. Wait and retry, as you would after a timeout.

Bulk events

For bulk event submissions, the key also identifies the job. Resubmitting with the same key returns the original job_id.