Idempotency
There are two ways of getting data into Metronome:
- Event ingestion via the
/ingestAPI endpoint or with our Segment integration. - API requests for resource creation, such as
POSTing to create a customer or credit pool.
These two types of data are handled differently due to their nature and scale.
Event Data
Event data is streamed to Metronome in bulk at high scale, making it impractical for the client to confirm receipt of individual data points. As such, the Metronome system is architected around the concept of unique transaction IDs per event. Once a usage event has been accepted with a given transaction ID, Metronome will ignore subsequent events within the next 34 days with the same transaction ID. This allows clients to safely send (and resend) events to Metronome, while ensuring each unique event is processed exactly once. See Getting usage data into Metronome for more details about usage events.
API requests
Separately, when creating or updating resources via the Metronome REST API, you often want to ensure a change is enacted while also avoiding the possibility of double writing. For this purpose Metronome supports sending an Idempotency-Key header. If the Idempotency-Key header is provided, and the request begins executing (it passed validation and doesn't conflict with another concurrent request), the results of the API call are persisted (even in the case of an HTTP 500 error), and returned for subsequent requests with the same key. The idempotency-key is expected to be unique per request, and reusing an idempotency-key for a request with different parameters will error with an HTTP 409 status code, preventing accidental reuse. This allows clients to safely retry requests without worrying about double writes.
The cache is periodically pruned but guarantees ≥ 24 hour protection.