Request Idempotency

INFO

This documentation is work in progress and subject to change. If you have any questions or feedback, please reach out to us via Support.

Zetl API has idempotency support for safely retrying requests without accidentally causing duplicate operation such as creating or updating resources.

For example, in case of connection failure, you can safely retry the same request and rest assured that it will not trigger the same operation.

When you send an idempotent request with this feature enabled, we will cache the resulting status code and response body of the first request made with a given key, regardless whether that process return success or failure, this including any 4xx errors such validation or 5xx server errors.

Idempotent request must have Idempotency-Key: <key> attached to its header. The header value should be uniquely generated by you which will be used as a key to identify subsequent retries of the same request. We recommend using newly generated Version 4 UUIDs as a value to give you enough entropy and avoid collisions. Our system expects idempotency key to be up to 36 characters long.

HTTP

POST /v1/customers HTTP/1.1
Host: api.zetl.com
Content-Type: application/json
Authorization: Bearer <your-private-key>
Idempotency-Key: 88a3db9c-0f14-4a58-b1f6-8b2c43f8e2a1

{
  "external_customer_id": "f849111b-c6c8-4774-be27-a4b4615429a3",
  "contact_email": "foo@example.com",
  "contact_name": "Foo Bar",
  "contact_phone": "+85224141219",
  "contact_country": "HK",
  "company_name": "Foo Bar",
  "company_country": "HK",
  "company_sector": "Recruitment"
}

curl

curl --request POST \
  --url 'https://app.zetl.com/v1/customers' \
  --header 'Authorization: Bearer <your-private-key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 88a3db9c-0f14-4a58-b1f6-8b2c43f8e2a1' \
  --data '{
  "external_customer_id": "f849111b-c6c8-4774-be27-a4b4615429a3",
  "contact_email": "foo@example.com",
  "contact_name": "Foo Bar",
  "contact_phone": "+85224141219",
  "contact_country": "HK",
  "company_name": "Foo Bar",
  "company_country": "HK",
  "company_sector": "Recruitment"
}'

Our system set 24 hours time-to-live (TTL) for our idempotency layer, this will let you repurpose the same key for new request after the original cache has been pruned. And to indicate whether a response is coming from our idempotency feature, look for Idempotency-Replayed: true in the response header. You can also identify the original response id it cached from by looking at the Replayed-From header.

It's worth noting that we use supplied idempotency key and compare it with request method and path (url parameters will always be omitted) to form the final cache key and to prevent accidental key misuse. This mean you can safely use the same key for different request methods and paths, but we recommend always using different keys for each different requests regardless of method or path in order to avoid confusion.

INFO

Request idempotency feature is currently only supported for our application/json endpoints.

All POST, and PUT API methods accept idempotency keys. Sending idempotency keys in GET and DELETE methods should generally be avoided.