Skip to content
HeartBadge docs

Idempotency

How idempotency keys work on write endpoints, and how to design them correctly.

Every write endpoint accepts an idempotency key. A repeat of a request with the same key within the retention window returns the original response and does not create a second resource. This is how you make retries safe.

This page is being written.

The structure is fixed. The prose is being drafted from the source material and reviewed by HeartChain Labs before publication. If you need this information urgently, email docs@heartbadge.com .

What this page will cover

  • Where idempotency keys are accepted
  • Key retention window
  • Designing keys: deterministic from your source event
  • What happens on key collision with different payloads
  • Patterns for mint, reward distribution, and gift issuance