For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Logo
Resources
Log inGet a demo
Get startedAPI referenceImplementation
Get startedAPI referenceImplementation
  • Authentication
    • Merge Link
    • Prompt guide for Merge Link
    • Magic Link
    • Single integration
  • Reading data
    • Syncing best practices
  • Supplemental data
    • Overview
    • Remote Data
    • Custom objects
  • Writing data
    • Overview
      • Introduction
      • Nested
      • Async operations
      • Idempotency
  • Platform and account metadata
    • Integration metadata
    • Linked Accounts
  • Testing
    • Testing Merge's Unified API via Postman
  • Specifications
    • Schema properties
    • Model Context Protocol (MCP)
UnifiedAgent HandlerGateway
UnifiedAgent HandlerGateway
Resources
Log inGet a demo
On this page
  • Overview
Writing dataWrites

Idempotency

Learn how to make idempotent POST requests with automatic retries
Was this page helpful?
Previous

Async operations

Next

Programmatic Writes with /meta

Built with

Idempotent operations are currently in beta, reach out to your account representative or contact us for more information.

Overview

For POST operations, Merge supports idempotency for safely retrying requests without accidentally performing the same operation twice. To perform an idempotent request, include an Idempotency-Key header in POST requests to ensure the same request is not processed more than once. It’s recommended to use a V4 UUID, but any sufficiently unique string will work. The idempotency log is stored for 24 hours before it expires.

  • If the key is unique, Merge will store a log of the request, including the hashed request body, status code, and response body
  • If the same key is reused with identical parameters, Merge will return the previously stored response
  • If the key is reused with different parameters, the API will return a 400 error indicating an invalid reuse

Retries on failed asynchronous requests will automatically follow the rate-limiting and retry mechanisms in the API. This approach allows for more resilient, scalable integrations, minimizing duplicate requests and supporting asynchronous processing for heavier tasks.