Idempotency
Send an Idempotency-Key with a write. If you have to retry, the write happens once.
Why
A request can fail after we have saved the contact but before you get the answer. If you send it again without a key, you can add the contact twice. With a key, the second request returns the first answer and writes nothing.
How
Add an Idempotency-Key header to POST /api/v1/contacts and PATCH /api/v1/contacts/{id}. Use any string of 1 to 255 bytes that is yours for this one write, such as a UUID, or the id of the row or form submission that caused it.
curl -s -X POST https://app.contactz.app/api/v1/contacts \
-H "Authorization: Bearer $CZ_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: form-submission-18342" \
-d '{ "firstName": "Ada", "emails": [{ "label": "work", "value": "[email protected]" }] }'| You send | You get |
|---|---|
| The same key and the same body, within 24 hours | The first answer, with the same status. Nothing is written. |
| The same key and a different body | 422 idempotency_key_reused. Use a new key for a new write. |
| The same key while the first request is still running | 409 idempotency_key_in_progress. Wait a moment and send it again. |
| An empty key, a key over 255 bytes, or 2 keys | 400 idempotency_key_invalid. |
Without a key, nothing is remembered, and each request is a new write. See Errors for all the codes.