Idempotent Requests

Idempotent Requests are requests that can be called many times without producing different outcomes. GET and DELETE requests are idempotent by definition, meaning the same backend work will occur no matter how many times the same request is issued. POST requests, however, are not idempotent. Sending a successful POST request once will result in a newly created object. If you send the same POST request 5 times, you will create 5 resources, assuming none of those requests err. If a network error occurs, there is no deterministic way to ensure the exact number of resources created.

For this reason, we have added a feature that will allow you to safely resend the same POST request to /v1/postcards, /v1/letters, or /v1/checks and ensure that duplicate products are not created. To perform an idempotent POST request, you simply need to provide an additional Idempotency-Key header that uniquely identifies that resource. See our documentation for more specific information.

Generating Idempotency Keys

We suggest using V4 UUID or another appropriately random string, but how you create the unique keys is up to you. For example, if you would like to associate a check with an internal unique ID of the user you are sending the check to, you may use that user id and the transaction date as an idempotency key (as long as you can guarantee the uniqueness of each idempotency key across requests to the same product). This key will expire after 24 hours, meaning if you resend the same request with the same idempotency key after 24 hours, a second resource will be created. Ultimately, it is up to you to make sure that you are appropriately setting the uniqueness of your keys based on your business logic. See resources below for help generating V4 UUIDs in various languages.

Sending Requests on Retry

In case of failure, we recommend following something akin to an exponential backoff algorithm for retrying your idempotent requests. This ensures that you aren't retrying continuously on a downed server, thereby contributing to the issue at hand.


Below are resources we recommend in various languages for generating V4 UUIDs.