RailGuardDocs

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.

RequestResult
New keyNormal evaluation, stored with the key
Same key + same amount, merchant, rail, recipient200 replay of the original decision, idempotent_replay: true. No new evaluation, no new card.
Same key + changed amount/merchant/rail/recipient409 IDEMPOTENCY_MISMATCH. Send a new key to get a new evaluation.
No key, identical request within 10 min200 replay, duplicate_suppressed: true. No second card.
No key, otherwiseNew 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_key for retries.
  • Requests that were blocked the first time are not remembered: sending the same request again starts a new evaluation.
  • On 429, wait retry-after and resend with the same key.