Idempotency

How it works

The X-Idempotency-Key header

Mutating endpoints (POST, PUT, PATCH) require the X-Idempotency-Key header. This client-generated key lets the API detect and deduplicate repeated requests.

curl --request POST \
  --url https://api.sandbox.tracefinance.com/v1/operations/withdrawals \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  --header 'Content-Type: application/json' \
  --data '{ ... }'

When it is required

The X-Idempotency-Key header is required on any request that creates or modifies a resource. GET and DELETE requests do not require it.

Conflict behavior

If a request arrives with an idempotency key that was already used, the API returns HTTP 409 Conflict:

{
  "code": "IDEMPOTENT_ID_CONFLICT",
  "message": "A request with this idempotency key has already been processed.",
  "details": {}
}

Examples

Generate a UUID v4 for each unique operation:

Python
JavaScript

import uuid

idempotency_key = str(uuid.uuid4())

const idempotencyKey = crypto.randomUUID();

Retrying safely after a timeout:

# First attempt — times out
curl ... --header 'X-Idempotency-Key: 550e8400-...'

# Retry with the same key — safe, returns original result
curl ... --header 'X-Idempotency-Key: 550e8400-...'

Never reuse an idempotency key for a different operation. Each unique operation must have its own key.

Getting started

Compliance Requirements

API principles

Webhooks

Journeys

Overview

How it works

The X-Idempotency-Key header

When it is required

Conflict behavior

Examples

​Overview

​How it works

​The X-Idempotency-Key header

​When it is required

​Conflict behavior

​Examples

Overview

How it works

The X-Idempotency-Key header

When it is required

Conflict behavior

Examples