Skip to main content
Network calls fail in ambiguous ways: a request times out, but the client cannot know whether the server processed it. To retry safely, send an Idempotency-Key header. Trackly remembers the first successful result for that key and replays it on an exact retry, so protected work runs at most once.

​
Where it applies

Idempotency is supported on selected write endpoints, including: If you omit the header, the request runs normally with no idempotency protection. For each variable-resource Number Request mutation above, the replay fingerprint includes the concrete path as well as the body and query. Within that operation, an exact retry to the same request id replays, while the same key and payload sent to another request id returns 409 idempotency_conflict. Existing idempotent endpoints retain their established body-and-query fingerprint behavior.

​
How it behaves

​
The first successful (2xx) response is cached for 24 hours and returned verbatim — same body, same status code — on every retry. The handler does not run again.
​
Reusing a key with a different request body or query returns 409 idempotency_conflict. Path-bound operations also conflict when the concrete resource path changes. An idempotency key must identify one exact operation.
​
If a retry arrives before the original finishes, it returns 409 idempotency_in_progress with a Retry-After: 5 header. Wait and retry.
​
A non-2xx result releases the key — you can immediately reuse the same key to retry. This differs from providers that bind a key on first receipt; after fixing a 400, the same key can be retried with the corrected request.

​
Choosing a key

  • Use a value unique to the operation — a UUID, or a deterministic ID from your own system (e.g. create-child:loc_west).
  • Keys are ≤255 characters, printable ASCII. Longer or non-printable keys return 400 idempotency_key_too_long / idempotency_key_invalid.
Test and live keys are isolated. The idempotency namespace is separated by mode, so a sandbox key and a live key can use the same Idempotency-Key value without ever colliding.

​
Example

Retrying a child creation with the same key returns the original child, not a second account:
cURL
Run it twice with the same Idempotency-Key and you get the same 201 response both times — one child is created.
Idempotency protects against duplicate requests, while externalIds.locationId uniqueness protects against duplicate businesses created by different requests. Together they make child provisioning safe to retry from anywhere.