Skip to main content
Send the same Idempotency-Key when you retry a write after a timeout. Guile returns the original result instead of running the write twice.

​
What you do first

  1. Generate a new key for each distinct write you mean to run once (a V4 UUID is fine).
  2. Put it on the Idempotency-Key header of the mutating call.
  3. On retry of that same write, send the same key and the same body.
Money writes that require a key include creating an instant payout. Other mutating calls may accept a key optionally, check the operation.

​
States that matter

Keys are scoped per operation. Changing the body with the same key does not re-run the write with new parameters. Keys stay valid for 24 hours for replay on the operations that document that retention. They are not searchable. Keep the resource id from the first success and use that for later reads.

​
When a call fails

If the connection ends before a response arrives, treat the write outcome as unknown. Retry the exact request with the same idempotency key so Guile can return the original result instead of running a second write. Do not invent a new key after an ambiguous timeout.
  • Appointments: creates need a key so a same-key retry can replay the first result
  • Payments: card-present writes that move money
  • Problem types: how to read a failure