{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-@l10n/en-US/apis/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["code-group"]},"type":"markdown"},"seo":{"title":"Idempotency","description":"Documentação oficial da API da plataforma de crédito embarcado Dinie. Integre produtos de crédito diretamente na sua aplicação.","siteUrl":"https://docs.dinie.com","lang":"pt-BR","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"idempotency","__idx":0},"children":["Idempotency"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Network failures, timeouts, and retries are a reality of distributed systems. The Dinie API supports ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["idempotency keys"]}," so you can safely resend ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," requests without accidentally creating duplicate resources."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-is-idempotency","__idx":1},"children":["What is Idempotency?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An operation is idempotent if executing it multiple times produces the same result as executing it once. For example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE"]}," are naturally idempotent -- fetching or deleting the same resource twice has the same effect. But ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," (creation) is not naturally idempotent -- sending it twice may create two resources."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]}," header makes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"using-the-idempotency-key-header","__idx":2},"children":["Using the Idempotency-Key Header"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Include an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]}," header in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," requests that create resources:"]},{"$$mdtype":"Tag","name":"CodeGroup","attributes":{"mode":"tabs"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","data-title":"Node.js","header":{"title":"Node.js","controls":{"copy":{}}},"source":"const customer = await dinie.customers.create(\n  {\n    cpf: \"123.456.789-00\",\n    name: \"Joao Silva\",\n    email: \"joao@example.com\",\n  },\n  { idempotencyKey: \"partner-onboard-joao-2026-03-04\" }\n);\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","data-title":"Ruby","header":{"title":"Ruby","controls":{"copy":{}}},"source":"customer = dinie.customers.create(\n  cpf: \"123.456.789-00\",\n  name: \"Joao Silva\",\n  email: \"joao@example.com\",\n  idempotency_key: \"partner-onboard-joao-2026-03-04\"\n)\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","data-title":"Python","header":{"title":"Python","controls":{"copy":{}}},"source":"customer = dinie.customers.create(\n    cpf=\"123.456.789-00\",\n    name=\"Joao Silva\",\n    email=\"joao@example.com\",\n    idempotency_key=\"partner-onboard-joao-2026-03-04\",\n)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","data-title":"cURL","header":{"title":"cURL","controls":{"copy":{}}},"source":"curl -X POST https://sandbox.api.dinie.com.br/v3/customers \\\n  -H \"Authorization: Bearer dinie_at_...\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: partner-onboard-joao-2026-03-04\" \\\n  -d '{\n    \"cpf\": \"123.456.789-00\",\n    \"name\": \"Joao Silva\",\n    \"email\": \"joao@example.com\"\n  }'\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"supported-operations","__idx":3},"children":["Supported Operations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Idempotency keys are supported on all ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," requests that create resources:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Endpoint"},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v3/customers"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create a customer"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v3/customers/{id}/kyc-attachments"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Upload a KYC attachment"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v3/credit-offers/{id}/simulations"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Run a simulation"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v3/loans"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create a loan"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v3/auth/credentials"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create an API credential"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v3/webhooks/endpoints"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create a webhook endpoint"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v3/webhooks/endpoints/{id}/secret/rotate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rotate webhook secret"]}]}]}]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Info:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE"]}," are naturally idempotent and do not require the header. You can safely resend these requests without any special handling."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":4},"children":["How It Works"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You send a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," request with an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]}," header"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The API processes the request and caches the response, indexed by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["(partner_id, idempotency_key)"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If you send the same key again within 24 hours, the API returns the cached response without reprocessing"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["After 24 hours, the cached response expires and the key can be reused"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"cache-window","__idx":5},"children":["Cache Window"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Idempotency keys are cached for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["24 hours"]},". After that period:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The key expires and the cached response is discarded"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sending the same key will process a new request"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If you need to resend after 24 hours, use a new idempotency key"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handling-collisions","__idx":6},"children":["Handling Collisions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you send the same idempotency key with a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Warning:"]}," Always use unique idempotency keys for different operations. A good pattern is to combine a semantic prefix with a unique identifier:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create-customer-{external_id}"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create-loan-{offer_id}-{timestamp}"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["upload-doc-{customer_id}-{doc_type}"]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"generating-keys","__idx":7},"children":["Generating Keys"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Choose a strategy that ensures uniqueness across your entire application:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Strategy"},"children":["Strategy"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"When to use"},"children":["When to use"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["UUID v4"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["550e8400-e29b-41d4-a716-446655440000"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["General purpose, always unique"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Business ID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create-customer-partner-ref-123"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When you want natural deduplication"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Composite"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loan-{offer_id}-{installments}-{amount}"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When parameters define uniqueness"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sdk-behavior","__idx":8},"children":["SDK Behavior"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDKs automatically generate a UUID as the idempotency key for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["every ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," request"]},", regardless of retry configuration. This ensures that POST requests never create duplicate resources, even in network failure scenarios."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"automatic-mode-default","__idx":9},"children":["Automatic mode (default)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK generates a unique UUID for each POST call. You don't need to do anything:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const dinie = new Dinie({\n  clientId: process.env.DINIE_CLIENT_ID,\n  clientSecret: process.env.DINIE_CLIENT_SECRET,\n});\n\n// The SDK automatically generates an Idempotency-Key UUID for this request\nconst customer = await dinie.customers.create({\n  cpf: \"123.456.789-00\",\n  name: \"Joao Silva\",\n  email: \"joao@example.com\",\n});\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"explicit-mode","__idx":10},"children":["Explicit mode"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Pass your own key when you need deterministic deduplication based on business logic. The explicit key overrides the automatically generated one:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"// Use a key based on business identifiers for natural deduplication\nconst customer = await dinie.customers.create(\n  {\n    cpf: \"123.456.789-00\",\n    name: \"Joao Silva\",\n    email: \"joao@example.com\",\n  },\n  { idempotencyKey: \"create-customer-partner-ref-123\" }\n);\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use explicit keys when:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The operation must be deduplicated based on business identifiers (not just per-request)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Different parts of the system may attempt the same operation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You need to correlate retries with the original operation"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":11},"children":["Best Practices"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Always use idempotency keys"]}," for loan creation (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v3/loans"]},"). This is a financial operation where duplicates are costly."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use deterministic keys"]}," based on business identifiers when possible. This provides natural deduplication even across separate retry attempts."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Store the idempotency key"]}," alongside your internal record to correlate retries with the original operation."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Do not reuse keys"]}," for different operations, even after the 24-hour window."]}]}]},"headings":[{"value":"Idempotency","id":"idempotency","depth":1},{"value":"What is Idempotency?","id":"what-is-idempotency","depth":2},{"value":"Using the Idempotency-Key Header","id":"using-the-idempotency-key-header","depth":2},{"value":"Supported Operations","id":"supported-operations","depth":2},{"value":"How It Works","id":"how-it-works","depth":2},{"value":"Cache Window","id":"cache-window","depth":2},{"value":"Handling Collisions","id":"handling-collisions","depth":2},{"value":"Generating Keys","id":"generating-keys","depth":2},{"value":"SDK Behavior","id":"sdk-behavior","depth":2},{"value":"Automatic mode (default)","id":"automatic-mode-default","depth":3},{"value":"Explicit mode","id":"explicit-mode","depth":3},{"value":"Best Practices","id":"best-practices","depth":2}],"frontmatter":{"seo":{"title":"Idempotency"}},"lastModified":"2026-03-15T13:30:00.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/en-us/apis/concepts/idempotency","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}