Idempotency

A request that moves money must be safe to send twice. Every write takes an Idempotency-Key, and the key decides whether a request is new.

How it behaves

Send a key of your choosing, 255 characters or fewer, on every write. A UUID per intended action is the usual choice.
Repeating the request with the same key returns the original result with 200. Nothing happens a second time.
The same key with a different request is refused with 422 and the code idempotency_key_reused.
If the first request is still running, the repeat answers 409 with idempotency_in_progress, which is safe to retry.

When to retry

After a timeout or a dropped connection you cannot know whether the write happened. Send the same request again with the same key: either it happens now, or you get the result from the first time. Every problem also says whether it is worth retrying in its retryable field; see Errors.