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

# Idempotency

Method's API supports idempotency for safely retrying requests without accidentally performing the
same operation twice. This helps avoid unwanted duplication in case of failures and retries. For
example, in the case of a timeout error, it is possible to safely retry sending the same API payment
call multiple times with the guarantee that the payment will only be created once.

Method's idempotency works by saving the resulting status code and body of the first request
made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent
requests with the same key return the same result, including `500` errors.

#### Enable idempotency

To submit a request for idempotent processing, send a request with
the `Idempotency-Key: <key>` header. The `<key>` can be any unique string
up to 255 characters long. (We recommend using V4 UUIDs). All `POST` requests accept
idempotency keys.

#### Idempotency error

In the unlikely event that the idempotent data store is unavailable, the API returns
a `503` error status with a sub type of `IDEMPOTENCY_UNAVAILABLE`. If idempotency
is required, we recommend retrying your request later, otherwise, fall back to non-idempotent processing by
not submitting the `Idempotency-Key` header.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/payments \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Idempotency-Key: 24c47283-0cc8-43a0-8b4a-ce16d002de97" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 5000,
      "source": "acc_JMJZT6r7iHi8e",
      "destination": "acc_AXthnzpBnxxWP",
      "description": "Loan Pmt"
    }'
  ```

  ```javascript Node.js theme={null}
  const payment = await method.payments.create({
    amount: 5000,
    source: 'acc_JMJZT6r7iHi8e',
    destination: 'acc_AXthnzpBnxxWP',
    description: 'Loan Pmt',
  }, {
    idempotency_key: '24c47283-0cc8-43a0-8b4a-ce16d002de97',
  });
  ```

  ```python Python theme={null}
  payment = method.payments.create({
    'amount': 5000,
    'source': 'acc_JMJZT6r7iHi8e',
    'destination': 'acc_AXthnzpBnxxWP',
    'description': 'Loan Pmt',
  }, {
    'idempotency_key': '24c47283-0cc8-43a0-8b4a-ce16d002de97'
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "error": {
      "type": "API_ERROR",
      "code": 503,
      "sub_type": "IDEMPOTENCY_UNAVAILABLE",
      "message": "Idempotent requests are temporarily unavailable. To ensure idempotency try your request later, or fall back to a non-idempotent request."
    }
  }
  ```
</ResponseExample>