API Idempotency

Overview

Idempotency is a property of an API endpoint that ensures the same request can be made multiple times without causing different outcomes.

• POST requests are not idempotent, because they create new resources.

• GET, PUT, and DELETE requests are always idempotent by definition.

• Our particular implementation of PATCH requests is idempotent, and therefore safe to retry.

Idempotency-Key Header

You can use the Idempotency-Key header to deduplicate POST requests.

If you include this header in your request, we will ensure that the request is only processed once, even if it is made multiple times.

const response = await fetch(`https://api.ittybit.com/files`, {
  method: "POST",
  headers: {
    "Authorization": "Bearer ITTYBIT_API_KEY",
    "Idempotency-Key": "my-unique-idempotency-key",
  },
  body: JSON.stringify({
    url: "https://ittyb.it/sample.mp4",
  }),
});

This is useful for requests that may be retried by your system, for example if your system crashes before it can process the response from the API.

Valid Keys

The Idempotency-Key header must be a unique string between 16 and 32 characters in length.

A good option is to generate a hash from the values you are sending in the request.

Expiry

Idempotency keys are valid for ~24 hours from first creation. After this time, the key will expire and the request will no longer be deduplicated.

Errors

Sending different request bodies with the same Idempotency-Key will result in an error.