Idempotent Requests

Documentation | Checkbook

When sending data across the Internet, there are many times when the unexpected happen. For example, a check could get created in our system, but due to a network issue the API response never gets back to the originator.

Our API supports idempotency so you can safely retry your requests without having to worry about a duplicate operation. User, bank account, check and invoice creation all support the Idempotency-Key header as part of the POST request.

This should be a unique key (it can be a counter, timestamp, UUID, etc) no longer than 255 characters that will not be re-used with that particular POST endpoint. 
If you make the same request with the same idempotent key, no new resource will be created on our end, but you will receive the same response as the first time. 
However, if you re-use an idempotent key with different parameters, the idempotent key will be ignored.

For example, if you create a new user with the email address [email protected], you will receive a response containing the keys for the new user. If this request has a header of Idempotency-Key: 1 and you repeat the same request (creating a user with email address [email protected]), you will receive the same API keys as in the initial request.

However, if you create a new user, [email protected], with a header of Idempotency-Key: 1 , a new user with a new set of API keys is created, even though the idempotent key was reused.

Another important detail is that the idempotent key only lasts for 3 minutes. 
So if you repeat the same request and reuse the idempotent key after more than 3 minutes, then the request will be considered as a new one and the idempotent key will be ignored.