How it works
- Add
Idempotency-Key: <unique value>to a write. A random UUID per logical operation is a good key. Every write operation of the API reference accepts it. - The same key with the same body within 24 hours returns the stored answer: same status, same body. Nothing runs twice.
- The same key with a different body is
422 IDEMPOTENCY_KEY_REUSED. Use a new key for a new request. - The same key while the first request is still running is
409 IDEMPOTENCY_IN_PROGRESSwithRetry-After: 2. Wait and send the same request again. - A request that failed is not stored: retry it with the same key and it runs again.
- Keys are scoped to the tenant, the caller, your app, the method and the path. Two apps, or two different operations, never share a key.
- Without the header the server makes up a key, so retries are not deduplicated. The key in use comes back in the
Idempotency-Keyresponse header.
curl -sS https://api.stracker.vn/v1/trips \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7b6a2c0e-5c53-4b60-9b3e-2d1f6a0c9d11" \
-d '{"routeId": 4, "date": "2026-11-20"}'Secrets are never replayed
The answers that show a secret once (creating a webhook subscription, rotating its secret) are stored without the secret. A replay returns the same subscription but no secret. If you lost the first response, rotate the secret and keep the new one.
When to retry
- Retry with the same key: a network error or timeout, a
5xx, a429(afterRetry-After), a409 IDEMPOTENCY_IN_PROGRESS. - Do not retry a
4xxthat is about the request itself (400,403,404,409for a conflict): fix the request and use a new key. - Reads (
GET) are safe to repeat and need no key.