> ## 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. Subsequent requests with the same key normally return the
same saved result. If a network or gateway failure leaves the result unknown, Method checks
the original operation and recovers its recorded response. A recorded error can also be
replayed. Method releases the key for a retry with the same parameters only when it has
sufficient evidence that the original operation was not received.

#### 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.

#### Recovering from errors

If a request submitted with an idempotency key fails with a transient error, such as a `500`,
a timeout, or a dropped connection, retry the request with the same parameters and the
same `Idempotency-Key`. Method reconciles interrupted requests and returns the recorded
result when it is available. That result can be a success or an error.

Avoid switching to a new idempotency key without first confirming the request's status
with Method; this approach risks duplicating the operation. Retrying with the original key
is always safe.

In rare cases, an error may continue to be returned after retries with the same key.
If the error persists, contact support to confirm the request's status. Once we confirm that the operation was not
performed, we can either clear the key so your retries
with the original key succeed, or you can safely retry with a new idempotency key.

#### Idempotency errors

Use `error.sub_type` to select the next action. All retries must use the same
parameters and `Idempotency-Key`.

| HTTP status | `error.sub_type` | Action |
| - | - | - |
| `500` | `IDEMPOTENCY_PENDING` | Retry later with the same key. Method can continue to check the original request. |
| `500` | `INTERNAL_BAD_STATE` | Contact support to confirm the result before you use a new key. |
| `503` | `IDEMPOTENCY_UNAVAILABLE` | The idempotency service is unavailable. Retry later with the same key. |

`IDEMPOTENCY_PENDING` does not mean that the original request failed. Method keeps
the key locked while it checks the result. A retry can return the recorded response,
including a recorded error. A retry can also return another pending response.

```json theme={null}
{
  "error": {
    "type": "API_ERROR",
    "code": 500,
    "sub_type": "IDEMPOTENCY_PENDING",
    "message": "This request is pending finalization. Retry your request again with the same idempotency key."
  }
}
```

`INTERNAL_BAD_STATE` means that Method cannot offer automatic recovery for this
response. For example, the saved response can exceed the storage limit, or the
background recovery period can have ended. This error does not prove that the
operation failed or that the key can never recover.

```json theme={null}
{
  "error": {
    "type": "API_ERROR",
    "code": 500,
    "sub_type": "INTERNAL_BAD_STATE",
    "message": "Contact support to confirm the request outcome. Do not submit this request with a new idempotency key."
  }
}
```

#### Log an idempotency error

Record these fields in your application logs when a request fails:

* The HTTP method, path, status, and time.
* The `Idempotency-Key` that you sent.
* The response headers `Request-Id`, `Idem-Request-Id`, and `Idem-Status`, when present.
* `error.code`, `error.sub_type`, and `error.message`.

Send these details to support if the error continues. Keep the original key for all
retries. Do not log your API key or the `Authorization` 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. Retry later with the same idempotency key."
    }
  }
  ```
</ResponseExample>


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