Idempotent Requests

The Circle APIs support idempotent requests so that you can safely retry API calls when things go wrong before you receive a response.

For instance, let's say you were creating a payment but before you received a response there was a network connection issue. Did the payment get created? Is it safe to retry or are you going to charge your end user multiple times?

To allow you to retry certain requests without causing the operation to be executed multiple times, Circle APIs' POST operations have an idempotency body parameter called idempotencyKey.

To ensure a request is idempotent you have to generate and provide such parameter. Subsequent requests with the same idempotencyKey parameter value will produce the same result as the initial request.

📘

UUID Format

The idempotencyKey body parameter has to be sent in UUID format.

The following Circle API operations support idempotent requests. Check the API reference for more details.

• Core Functionality
  • Create a payout.
  • Create a bank account (wires).
  • Create a transfer.
  • Generate a deposit address.
  • Add a recipient address.
• Payments API
  • Create a payment.
  • Cancel a payment.
  • Refund a payment.
  • Create a card.
  • Create a bank account (wires).
• Payouts API
  • Create a payout.
  • Create a bank account (wires).
  • Create a transfer.
• Accounts API
  • Create a wallet.
  • Generate a blockchain address.
  • Create a transfer.