> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackra.figentra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 0036 — Idempotency keys in Encore cache for 24 hours; Postgres for money

> Superseded by 0136 · 2026-10-20

> [!NOTE]
>
> Superseded by [0136](/adr/0136-action-runtime-contract): idempotency moves to the cache package,
> and the handler contract is in that ADR.

## Context

Non-GET endpoints accept an `Idempotency-Key`, and the mobile mutation queue retries with keys. A cache is cheap but can evict; money must never be applied twice or forgotten.

## Decision

1. **Idempotency keys are stored in the Encore cache with a 24-hour TTL**, with the response, scoped per tenant and endpoint.
2. **Money-moving operations record their key in Postgres**, in the same transaction as the ledger entry; the key is kept as long as the entry.
3. A repeated key with a different payload returns a conflict, not the stored response.
4. Retries within the window return the original response.

## Consequences

* Fast duplicate protection for ordinary writes; a duplicate arriving after 24 hours is treated as new.
* Payments carry a durable guarantee at the cost of a database write.

## Enforcement

Planned — a shared idempotency helper with a conformance test; a check that endpoints under payments/ledger do not use the cache-only helper.

## Supersedes and sources

Supersedes: none. Sources: owner decisions in chat, 2026-10-19; `.agents/rules/http-conventions.md`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.