Skip to main content
Send an Idempotency-Key header on every write, and retry a failed or timed-out write with the same key. The general rules are on Idempotency; this page covers what is specific to partner keys.

​
The header

  • One key per logical operation, at most 255 characters from A-Z a-z 0-9 _ - : .. A UUID works; so does an id from your own system, such as withdrawal-90311.
  • A 2xx response is stored for 24 hours. A retry with the same key and the same request returns the stored response, with its original status and body, plus the header Idempotent-Replay: true. Nothing runs again.
  • The same key with a different request is 409 IDEMPOTENCY_KEY_CONFLICT. The same key while the first request is still running is 409 IDEMPOTENCY_REQUEST_IN_PROGRESS.
  • Errors are not stored: after a 4xx or 5xx you can fix the request and retry with the same key.

​
Scope

For a partner key, stored responses are keyed on your organisation, the account and the route:
  • on routes that act for an account, the account in Kash-Account;
  • on /v1/partner/accounts/{accountId}/... routes, the account in the path;
  • on POST /v1/partner/accounts, your organisation alone.
So one key used for two of your accounts is two independent requests.

​
Per route

​
Creating an account twice

​
Detecting a replay

A replay returns the stored body unchanged, so its _meta.idempotent is whatever the first answer said. Check the Idempotent-Replay: true header to detect an HTTP-level replay.

​
With the SDK

@kashdao/sdk sends an Idempotency-Key on every POST automatically and reuses it across its own retries. Pass your own with { idempotencyKey } on trades.create when you want the key to survive a restart of your process. In 0.4.0, partnerAccounts.create also accepts { idempotencyKey }, and partnerAccounts.withdrawals.create requires it.