Idempotency and retries
Why this beats a plain card limit.
Send idempotency_key in the body (or an Idempotency-Key header) on POST /api/public/transactions. Keys are scoped per agent.
| Request | Result |
|---|---|
| New key | Normal evaluation, stored with the key |
| Same key + same amount, merchant, rail, recipient | 200 replay of the original decision, idempotent_replay: true. No new evaluation, no new card. |
| Same key + changed amount/merchant/rail/recipient | 409 IDEMPOTENCY_MISMATCH. Send a new key to get a new evaluation. |
| No key, identical request within 10 min | 200 replay, duplicate_suppressed: true. No second card. |
| No key, otherwise | New evaluation |
sequence
Agent RailGuard Approver
| spend $250 (k1) | |
|---------------->| flagged ----------->|
| 202 | |
| retry $250 (k1) | |
|---------------->| replay, same txn |
| |<------- approve ----|
|<-- webhook: approved, 1 card ---------|
| spend $300 (k1) | |
|---------------->| 409 mismatch |
| spend $300 (k2) | |
|---------------->| new evaluation |Python
payment = guardrail.spend(amount=250, merchant="AWS", idempotency_key="order-8841")Limits
- A replay never returns the card secret again; it is handed out once. Poll the transaction for status.
- Changing the amount, merchant or category under the same key is refused with 409 — no second card is issued. A new key is a new payment; any unused single-use card from the original request is cancelled automatically after 24 hours, or immediately if an Approver rejects it.
- Without a key, an identical request sent more than 10 minutes later counts as a new payment — always send
idempotency_keyfor retries. - Requests that were blocked the first time are not remembered: sending the same request again starts a new evaluation.
- On 429, wait
retry-afterand resend with the same key.