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

Metronome supports two methods of ensuring idempotency through the REST API:

• Using uniqueness keys (on select endpoints)
• Using the Idempotency-Key header

Using uniqueness keys

Certain resources in Metronome include a field uniqueness_key in the payload. This uniqueness key is stored as part of the resource in Metronome, and Metronome ensures that no resources can share the same uniqueness key. If you attempt to create a resource with a uniqueness key already in use, you receive an HTTP 409 error with message “This uniqueness key has already been used.”

Examples of resources with uniqueness keys:

• Contract
• Alert

Idempotency-Key header

When creating or updating resources with 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

Metronome recommends using the Idempotency-Key header for endpoints that don’t include a dedicated idempotency key, or for actions that should only be evaluated once.