Metronome idempotency: the 34-day transaction_id window and 409 alias conflicts

TL;DR

Reuse the same transaction_id when retrying a failed ingest; duplicates inside 34 days are ignored, not double-counted. If you get a 409 on customer creation, the ingest alias is already taken, pick another or release it.

Steps

1. Reuse the same transaction_id when retrying a failed ingest; duplicates inside 34 days are ignored, not double-counted. If you get a 409 on customer creation, the ingest alias is already taken, pick another or release it. For non-ingest POSTs, send Idempotency-Key so a retried request does not create a duplicate resource.

When to use

You are seeing this: If you get a 409 on customer creation, the ingest alias is already taken, pick another or release it. Use this skill when you run into "Metronome idempotency: the 34-day transaction_id window and 409 alias conflicts".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Source: Official docs (Metronome API idempotency): documents that transactionid dedupes usage events over a rolling 34-day window, that reusing an ingest alias across customers returns 409 Conflict, that uniquenesskey conflicts also return 409 until released, and that the Idempotency-Key header caches POST responses for at least 24 hours.

Verified resolution: Reuse the same transaction_id when retrying a failed ingest; duplicates inside 34 days are ignored, not double-counted. If you get a 409 on customer creation, the ingest alias is already taken, pick another or release it. For non-ingest POSTs, send Idempotency-Key so a retried request does not create a duplicate resource.

Source URL: https://docs.metronome.com/api-reference/idempotency