# Rate limits and versioning

Treat `/v1` as the current path contract and use response headers rather than hardcoded request limits.

Authenticated responses expose `x-ratelimit-limit`, `x-ratelimit-remaining`, and `x-ratelimit-reset`; some guarded routes may also return `Retry-After`. A limit value can be dynamic or reported as `unlimited`.

1. Record the status, error code, and `x-request-id`.
2. On `429`, wait until `Retry-After` or `x-ratelimit-reset` when present.
3. Retry with exponential backoff, jitter, a maximum delay, and a maximum attempt count.
4. Cap client concurrency instead of launching a retry storm.
5. Do not retry non-idempotent work unless the route documents safe replay behavior.

Keep `/v1` in the base path and test migrations against documentation before changing it; no alternate public version header is required by the current routes.

**Expected result:** clients recover from transient limits without duplicate work and fail clearly on incompatible paths.