Idempotency

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.

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:

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.

JavaScript SDK

REST API

API reference

Webhooks

MCP

How Usertick handles the key

Endpoints that take the header

​How Usertick handles the key

​Endpoints that take the header

How Usertick handles the key

Endpoints that take the header