Idempotency

Idempotency lets you safely retry requests without risk of performing the same operation twice. This is useful when a request is interrupted by a network error or a timeout: you can retry it with confidence, knowing that the operation runs at most once.

Casharc supports idempotency for all POST requests — any request that creates a payment or changes its state. GET requests are naturally idempotent and never require a key.

Sending an idempotency key

To make a request idempotent, provide a unique value in the Idempotency-Key header. The key may be any string up to 255 characters; we recommend a UUID.

Send a distinct key for each distinct operation. Reusing a single key across different operations on the same payment — for example, creating it and later refunding it — is not supported, because each operation carries a different request body.

The first request with a given key is executed and its response is stored. Any later request with the same key returns that stored response — including the same status code and body — instead of running the operation again.

How keys behave

Situation	Result
Same key, same request body	Returns the stored response of the original request.
Same key, different request body	Returns an error: the key has already been used with different parameters.
Same key while the first request is still in progress	Returns an error: a request with this key is already being processed.
Key reused after it has expired	Treated as a new request.

Idempotency keys are stored for 24 hours. After a key expires, it can be used again for a new request.

Keys are scoped to your account, so they never collide with keys used by other accounts.

Which requests to send a key with

We recommend sending an idempotency key with every POST request. It is strongly recommended for requests that move money — creating a payment or issuing a refund — where an accidental retry would otherwise result in a duplicate operation.

Lifecycle actions such as claiming or canceling a payment are already guarded by the payment's status, but sending a key still protects against duplicate submissions and is recommended.

Sending an idempotency key#

How keys behave#

Which requests to send a key with#

Sending an idempotency key

How keys behave

Which requests to send a key with