Idempotency

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Network failures, timeouts, and retries are a reality of distributed systems. The Dinie API supports idempotency keys so you can safely resend POST requests without accidentally creating duplicate resources.

What is Idempotency?

An operation is idempotent if executing it multiple times produces the same result as executing it once. For example, GET and DELETE are naturally idempotent -- fetching or deleting the same resource twice has the same effect. But POST (creation) is not naturally idempotent -- sending it twice may create two resources.

The Idempotency-Key header makes POST requests idempotent by associating the request with a unique key. If the same key is sent again, the API returns the cached response from the first request instead of processing a new one.

Using the Idempotency-Key Header

Include an Idempotency-Key header in POST requests that create resources:

const customer = await dinie.customers.create(
  {
    cpf: "123.456.789-00",
    name: "Joao Silva",
    email: "joao@example.com",
  },
  { idempotencyKey: "partner-onboard-joao-2026-03-04" }
);

Supported Operations

Idempotency keys are supported on all POST requests that create resources:

Info: GET, PATCH, and DELETE are naturally idempotent and do not require the header. You can safely resend these requests without any special handling.

How It Works

1. You send a POST request with an Idempotency-Key header
2. The API processes the request and caches the response, indexed by (partner_id, idempotency_key)
3. If you send the same key again within 24 hours, the API returns the cached response without reprocessing
4. After 24 hours, the cached response expires and the key can be reused

Cache Window

Idempotency keys are cached for 24 hours. After that period:

• The key expires and the cached response is discarded
• Sending the same key will process a new request
• If you need to resend after 24 hours, use a new idempotency key

Handling Collisions

If you send the same idempotency key with a different request body, the API returns the cached response from the first request. It does not compare request bodies -- the key alone determines the cached response.

Warning: Always use unique idempotency keys for different operations. A good pattern is to combine a semantic prefix with a unique identifier:

• create-customer-{external_id}
• create-loan-{offer_id}-{timestamp}
• upload-doc-{customer_id}-{doc_type}

Generating Keys

Choose a strategy that ensures uniqueness across your entire application:

SDK Behavior

The SDKs automatically generate a UUID as the idempotency key for every POST request, regardless of retry configuration. This ensures that POST requests never create duplicate resources, even in network failure scenarios.

Automatic mode (default)

The SDK generates a unique UUID for each POST call. You don't need to do anything:

const dinie = new Dinie({
  clientId: process.env.DINIE_CLIENT_ID,
  clientSecret: process.env.DINIE_CLIENT_SECRET,
});

// The SDK automatically generates an Idempotency-Key UUID for this request
const customer = await dinie.customers.create({
  cpf: "123.456.789-00",
  name: "Joao Silva",
  email: "joao@example.com",
});

Explicit mode

Pass your own key when you need deterministic deduplication based on business logic. The explicit key overrides the automatically generated one:

// Use a key based on business identifiers for natural deduplication
const customer = await dinie.customers.create(
  {
    cpf: "123.456.789-00",
    name: "Joao Silva",
    email: "joao@example.com",
  },
  { idempotencyKey: "create-customer-partner-ref-123" }
);

Use explicit keys when:

• The operation must be deduplicated based on business identifiers (not just per-request)
• Different parts of the system may attempt the same operation
• You need to correlate retries with the original operation

Best Practices

1. Always use idempotency keys for loan creation (POST /v3/loans). This is a financial operation where duplicates are costly.
2. Use deterministic keys based on business identifiers when possible. This provides natural deduplication even across separate retry attempts.
3. Store the idempotency key alongside your internal record to correlate retries with the original operation.
4. Do not reuse keys for different operations, even after the 24-hour window.