Helium MVNEdocs

Idempotency

Every mutating Helium MVNE endpoint (POST, PUT, DELETE) accepts an Idempotency-Key request header. Set it, and Helium MVNE will return the same response for the same key — no duplicate side effects — for 24 hours.

Idempotency-Key: 9d4b5b16-5b4f-4f0b-b4d1-7b6a9a3e2c3d

Generate the key on the client side before the request goes out — typically a UUIDv4 per logical operation. Reusing a key for a genuinely new operation is an error.

Scoping

Idempotency keys are scoped by (operator_id, environment_id). You can reuse the same string in sandbox and live without collision, and no other operator can ever collide with yours.

When a replay happens

If Helium MVNE sees a key that's already completed, it replays the original response byte-for-byte, with an extra header:

Idempotency-Replayed: true

If it sees a key whose original request is still in-flight, it returns 409 Conflict — retry after the in-flight attempt resolves.

What to key on

  • Cron jobs that fire every N minutes: key on (job_name, run_at).
  • User-initiated actions: key on a per-action UUID captured once in your UI.
  • Webhook handlers that re-process deliveries on retry: key on the event's id.

What not to key on

  • The wall clock alone. Two requests can arrive in the same second.
  • An incrementing integer with no scope. You will collide across environments or restarts.