Idempotent Requests

The Zepto API supports idempotency for safely retrying requests without accidentally performing the same operation twice.

For example, if a [Make a Payment] is POSTed and a there is a network connection error, you can retry the Payment with the same idempotency key to guarantee that only a single Payment is created. In case an idempotency key is not supplied and a Payment is retried, we would treat this as two different payments being made.

To perform an idempotent request, provide an additional Idempotency-Key:<key> header to the request.

You can pass any value (up to 256 characters) as the key but we suggest V7 UUIDs or another appropriately random string.

Keys expire after 24 hours. If there is a subsequent request with the same idempotency key within the 24 hour period, we will return a 409 Conflict.

• The meta.resource_ref value is the reference of the resource that was previously created with the conflicting idempotency key.
• The Idempotency-Key header is required when interacting with endpoints that support it.
• Only the POST action for the Payments, Payment Requests, Transfers and Refunds endpoints require the use of the Idempotency-Key.
• Endpoints that use the GET or DELETE actions are idempotent by nature.
• A request that quickly follows another with the same idempotency key may return with 503 Service Unavailable. If so, retry the request after the number of seconds specified in the Retry-After response header.

Currently the following POST requests can be made idempotent. We require sending a unique Idempotency-Key header when making those requests to allow for safe retries:

• Request Payment
• Make a Payment
• Issue a Refund
• Add a Transfer