> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usertick.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> An Idempotency-Key on a POST makes a retry after a timeout safe, because Usertick never runs the request twice.

After a network error, a client can't always tell whether a POST went through. When the POST carries an `Idempotency-Key` header, the client can retry it without adding the same note twice or starting a second erasure job.

Every POST endpoint takes the header. The value is 1 to 255 printable ASCII characters without leading or trailing spaces, unique to the operation, such as a UUID generated once and reused on every retry of the same request.

```bash theme={null}
curl -X POST "https://app.usertick.com/api/public/v1/responses/9b1c2d3e-4f50-4a61-8b72-93a4b5c6d7e8/comments" \
  -H "Authorization: Bearer utk_live_your_key_here" \
  -H "Idempotency-Key: 4f3c1e2a-8b7d-4c6e-9a1f-2d3b4c5e6f70" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Shared with the payments team." }'
```

## How Usertick handles the key

| Request | Result |
| - | - |
| A key sent for the first time | Usertick runs the request and stores its HTTP response for 24 hours. |
| The same key with the same request | Usertick returns the stored HTTP response with `Idempotent-Replayed: true` and runs nothing a second time. |
| The same key with a different request | `409` with `PUB-002-002`. A new request needs a new key. |
| The same key while the first request still runs | `409` with `PUB-002-003` and `Retry-After: 1`, so the client can try again a moment later. |
| A key that is empty, too long or has characters outside printable ASCII | `400` with `PUB-002-001` |

"The same request" means the same method, path, parameters and body. A body sent again with different whitespace or key order counts as the same. Keys are stored per credential, so two keys or two apps never collide.

The stored HTTP response includes its status, body and `Location` header. A `5xx` response isn't stored, so a retry after a server error runs the request again.

Without the header, a POST runs every time it is sent.

## Endpoints that take the header

Every POST endpoint takes the header:

* [Add a note](https://docs.usertick.com/developers/api/reference/add-comment.md)
* [Erase a respondent](https://docs.usertick.com/developers/api/reference/erase-respondent.md)
* [Pause a survey](https://docs.usertick.com/developers/api/reference/pause-survey.md) and [resume a survey](https://docs.usertick.com/developers/api/reference/resume-survey.md)
* [Subscribe a URL](https://docs.usertick.com/developers/api/reference/subscribe-webhook.md)
* [Resend a delivery](https://docs.usertick.com/developers/api/reference/resend-delivery.md)

PATCH and DELETE don't take the header, and retrying them is safe without it. Sending the same PATCH twice leaves the response as the first PATCH left it. Once something is deleted, a second DELETE of it returns `404`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.