Rate-limit header checker

A limit and a remaining count let a client pace itself: a well-behaved integration slows down as the remaining count falls instead of accelerating into a refusal.

A reset value turns a 429 from a guess into a wait: the client knows when to retry rather than backing off by doubling and hoping.

Without either, the only way a client learns the limit is by exceeding it, which means every integration discovers your limits by failing in production at least once.

The headers are also the difference between a caller retrying politely and a caller retrying immediately, which is what turns a rate limit into a thundering herd.

A limit, a remaining count and a reset value on the responses of endpoints that are rate limited.

Values that move consistently as requests are made, rather than a constant echoed on every response.

A 429 accompanied by Retry-After, which is the one header a client can act on without any other context.

Consistency across the endpoints an integrator uses together, so one code path can read the budget rather than one per endpoint.

It means clients are not told their budget. It does not mean there is no limit, and the check reports it that way rather than as a missing control.

Many APIs limit at a gateway that does not surface the counters. The limiting works; the visibility does not.

This is why the finding here is informational. Adding the headers is a real improvement for integrators, and it is not a security fix.

The inverse is worth knowing too: headers present on every response is not proof that the limit is enforced, only that values are being sent.

Only the responses already received are read. No burst is generated and nothing is sent to find where the limit sits — that would be a load test, and this is not one.

An endpoint that is limited but returns no counters is indistinguishable from an endpoint that is not limited at all.

The header names in use vary between implementations, and an unconventional naming may not be recognised.

Whether the values are accurate cannot be established without provoking the limit, which is deliberately out of scope.

`api.ratelimit.headers` looks for standard rate-limit headers in the responses really received, and reports their absence as a lack of published information rather than as a missing control.

`api.surface.detected` supplies the endpoints whose responses are read.

Before opening an API to third-party integrators, because publishing the counters is what lets them build a client that backs off instead of one that hammers.

After introducing a gateway or moving the limiting to a new layer, since counters frequently stop being surfaced when the enforcement point moves.

When integrators report intermittent failures they cannot explain, which is the shape a silent limit takes from the outside.

After a limit is changed, as a published value left at the old number is worse than no value at all.