Using Idempotency Keys

Here's how to use idempotency keys with our API, in a way that means your requests will work every time.

Here's the basic flow for using one with an API call:

  1. Generate a unique string to use as the idempotency key.
  2. Send that key with the request, using the HTTP header Idempotency-Key.

That seems very simple, but there are a few things to keep in mind about how you generate the key and reusing keys in future requests.


Generating an Idempotency Key

You can only use a key for one single API request. For example, say that you're creating an order and the customer mis-types their postcode on the first request. When you send us a new order creation request, you'll need to send a new unique key with it.

So instead of using something like the customer number and/or order ID, you should either:

  • Generate a new UUID whenever the order details change.
  • Create a hash of the Order ID, Customer ID, and all the requested parameters together – so the key will change whenever the order details are changed.

Key Validity

You can use any string as your idempotency key. It'll be stripped of whitespace, then used to store your request and the response.

Your key must be unique for your account. If you're a multi-tenant site / reseller, that means the key needs to be unique across all the merchants on your platform.

If you reuse a key, you're telling us that your software is trying to perform the same request again, not make a new request (a failed order creation attempt and then a successful order attempt are two separate requests).

Thankfully, keys are destroyed after 72 hours – and after that, you can reuse them!

Once a key's used, you can't use it for a different endpoint or different parameters.

We thought about how to make the key system respond quickly and act safely. The best way to do that is to be strict in making sure you can't change endpoint or parameters once they've been associated with a key. This means it's easy to send back your response quickly.

If you do try to reuse a key with a different endpoint, you'll get a response like this one:

{
  "error": "conflict",
  "error_description": "The idempotency key you have requested already exists with different endpoint"
}

And reusing it with different parameters will get you a response like this:

{
  "error": "conflict",
  "error_description": "The idempotency key you have requested already exists with different params"
}

Ready To Go!

And now you should be ready to use idempotency keys!

If you're a reseller or writing an integration for a multi-tenant site (where multiple merchants' requests are sent with your API key), then you'll want to see this page where we give you extra security advice.

Here's a few notes about how we handle keys on our end, for clarity and to help with debugging:

  • After 24h, instead of returning the stored response we'll return an error message saying Value has already been taken.

  • After 72h, the key is cleared and can be reused (you shouldn't write your system to rely on this, but this lets you know how unique your idempotency keys need to be).

  • We don't cache 5XX error responses, but we may cache 4XX error responses.


Retrying requests

If your system submits a follow-up request with one of these keys too early – before the original request has been processed – then Sendle will return a HTTP 425 Too Early response.

Upon receiving this response, your system should wait a short while and then retry the exact same request.