Docs

Idempotency

A network error does not tell you whether the server saw your write. With an Idempotency-Key you can send it again without creating a second trip.

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_PROGRESS with Retry-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-Key response header.
curl
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, a 429 (after Retry-After), a 409 IDEMPOTENCY_IN_PROGRESS.
  • Do not retry a 4xx that is about the request itself (400, 403, 404, 409 for a conflict): fix the request and use a new key.
  • Reads (GET) are safe to repeat and need no key.