> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shorpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency and retries

> Retry requests safely and reconcile uncertain outcomes without duplicating actions.

Every POST requires `Content-Type: application/json` and `Idempotency-Key`, a unique intent identifier of 16–128 letters, digits, underscores or hyphens. Generate it once, persist it in your integration, and reuse it with exactly the same request for retries. Generate a new identifier for each intentional new action, even when its arguments are identical.

Successful operation results are retained for seven days. A completed retry returns the original result with `Idempotency-Replayed: true`; current resource state may since have changed. Never reuse an old key after retention. `externalReference` provides durable draft correlation after operation retention and is unique within the workspace and integration principal. Key rotation preserves that principal. An independently created key or a different MCP grant is a different integration.

## Retry policy

Retry transient network/502/503/504 errors with exponential backoff, preserving the key and payload for writes. Resolve validation, authorization and state conflicts before retrying.

A 429 response requires waiting for `Retry-After`. For `STALE_RESOURCE_VERSION`, fetch and review the latest state before creating a new intent. For `OPERATION_EXPIRED`, reconcile the resource before deciding whether to repeat an action. See [API errors](/developers/errors) for the complete recovery table.

The [TypeScript SDK](/developers/polling-and-sdk#typescript-client) documents its automatic retry policy.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.