API Idempotency

Applications often need to ensure that certain types of API calls, like creates and updates, successfully run exactly once. For this purpose, Metronome supports idempotency, allowing clients to safely retry requests without creating duplicate or extraneous data.

How you use idempotency depends on how you send data to Metronome:

• Event ingestion via the /ingest 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. For streamed data, Metronome effectively treats transaction IDs as idempotency keys.

Once a usage event has been accepted with a given transaction ID, Metronome ignores subsequent events with the same transaction ID within the next 34 days. This allows clients to safely send (and resend) events to Metronome, while ensuring each unique event is processed exactly once.

API requests

When creating or updating resources via the Metronome REST API, Metronome supports sending an Idempotency-Key header. If the Idempotency-Key header is provided, and the request begins executing (it passes validation and doesn't conflict with another concurrent request), the results of the API call are persisted, and the same results returned, per these rules:

• The Idempotency-Key is expected to be unique per request
• Reusing an Idempotency-Key for a request with different parameters errors with an HTTP 409 status code, preventing accidental reuse
• The cache is periodically pruned but guarantees ≥ 24 hour protection
• Idempotency works even in the case of an HTTP 500 error