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.

{
  "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.

{
  "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.

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"
  }'

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

payment = method.payments.create({
  'amount': 5000,
  'source': 'acc_JMJZT6r7iHi8e',
  'destination': 'acc_AXthnzpBnxxWP',
  'description': 'Loan Pmt',
}, {
  'idempotency_key': '24c47283-0cc8-43a0-8b4a-ce16d002de97'
})

{
  "error": {
    "type": "API_ERROR",
    "code": 503,
    "sub_type": "IDEMPOTENCY_UNAVAILABLE",
    "message": "Idempotent requests are temporarily unavailable. Retry later with the same idempotency key."
  }
}

API Reference

Entities

Accounts

Wallet

Payments

Files

Opal

Elements

Events

Supporting Endpoints

Enable idempotency

Recovering from errors

Idempotency errors

Log an idempotency error

​Enable idempotency

​Recovering from errors

​Idempotency errors

​Log an idempotency error

Enable idempotency

Recovering from errors

Idempotency errors

Log an idempotency error