Skip to main content

Idempotency

Mutable API operations require the Idempotency-Key header to ensure that an operation is not executed more than once in case of network retries.

Why use it?​

In distributed systems, a request can fail for various reasons (timeout, connection drop) after the server has already processed the operation. By repeating the request with the same Idempotency-Key, the server recognizes it as a duplicate and returns the result of the original operation without executing it again.

Endpoints that require Idempotency​

The Idempotency-Key header is required on all POST, PUT, and PATCH methods, including:

  • PIX Out transfers
  • Dynamic QR Code generation
  • Refund requests

How it works​

  1. First Request: The client sends the request with a unique Idempotency-Key (we recommend using UUID v4). The server processes the operation and stores the result.
  2. Subsequent requests (same key):
    • If the payload is identical, the server returns the previously stored result (HTTP 200/201/202).
    • If the payload is different, the server returns a conflict error (HTTP 409 idempotency_conflict).

Expiration​

Idempotency keys are stored for a period of 24 hours. After this period, the key expires and a new request with the same key will be treated as a new operation.

Best Practices​

  • Key Generation: Use universally unique identifiers (UUID). Do not try to reuse keys across different types of operations.
  • Retries: Implement a retry strategy with exponential backoff for network errors (5xx), always keeping the same Idempotency-Key.
  • Handling 409: If you receive a 409 idempotency_conflict, check whether you are trying to send a different operation with a key that was already used for another purpose.