Skip to main content
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 return the same saved result. If the first request fails with a transient error (e.g. a network disruption or a 500), Method automatically reconciles the state of the request so that a retry with the same key is safely reprocessed instead of replaying the error.

​
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 automatically reconciles interrupted requests, so retrying eventually returns a successful response, with the guarantee that the operation is performed at most once. 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, a request cannot be automatically reconciled and its saved error will continue to be returned. Method’s team is automatically alerted when this happens and will proactively reach out with the status of the affected requests. If you continue to receive the same replayed error for a key, 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 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.