Choosing keys

A good idempotency key is:

• Unique per logical operation. A UUID v4 per business event is the safest default.
• Stable across retries. Compute the key before the first attempt; reuse it on every retry.

UUID v4 is the recommended format. There is no hard length cap enforced today, but anything over a few dozen bytes is unusual. Stick to a UUID and you will not have to think about this.

A common pattern is to combine the action with a stable resource ID:

send-env_01HZX9P7K5T2RMS2GZ9C3V8N4Q
template-tpl_01HZX9-2026-05-03

Avoid timestamps, random per-attempt suffixes, or anything that varies across retries — those defeat the purpose.