Skip to main content
Networks fail. A request can time out after Talescria has already opened the account or sent the payment. To make retries safe, send an Idempotency-Key header: retrying with the same key returns the first answer instead of doing the work again.

Which requests need one

These writes require a key, and are refused with 400 IDEMPOTENCY_KEY_REQUIRED without one:
  • Open an account: POST /v1/accounts
  • Create a recipient or a destination: POST /v1/recipients, POST /v1/recipients/{id}/destinations
  • Send a payment: POST /v1/transfers
  • Transfer between your accounts: POST /v1/conversions
  • Create a payment link, customer, invoice or recurring series
Every other write accepts one too.

How keys behave

“The same request” means the same method, path and JSON body (key order doesn’t matter). If a request fails on our side with a 5xx, or the connection drops before a response, the key is released so your retry runs again. A 2xx or 4xx response is the answer for that key. Keys are kept for 24 hours and are scoped to your OAuth client: two clients can’t collide.

Choosing keys

  • One key per operation, not per attempt. Generate the key when you decide to make the payment, store it with your record, and reuse it on every retry. A fresh key per attempt defeats the purpose.
  • Format: 8 to 255 characters from A–Z a–z 0–9 - _ : .. A UUID works well. For transfers between your accounts, keep it to 100 characters.
  • Derive from your own IDs where that’s natural, for example payout:invoice_4821, so the same business action can never produce two payments.
For payments and transfers between your accounts, the key is also attached to the money movement itself, so money can’t move twice even if a request is interrupted part way through.