Review brief

Beginner20 min

An API gateway is exposing rate-limit state so clients can schedule retries. The limiter has already made its allow-or-deny decision; this helper receives that decision and owns only the public response headers.

Behavioral contract

limit is a positive integer, usedBeforeRequest is a nonnegative integer, and allowed is true exactly when usedBeforeRequest is less than limit. nowMs and resetAtMs are finite integer milliseconds, with resetAtMs later than nowMs.
RateLimit-Limit is the configured limit and RateLimit-Remaining is the nonnegative number of requests available after accounting for the current request; denied requests always report zero remaining.
RateLimit-Reset is the window end as an integer Unix timestamp in seconds, rounded up from resetAtMs.
Retry-After is present only for denied requests and is the positive integer number of seconds from nowMs until resetAtMs, rounded up with a minimum of one.
Return all header values as strings and do not expose the internal actor identifier in any response header.

Review instructions

1Review only the changed code against the behavioral contract in the brief.
2Anchor each finding to the narrowest useful changed line and explain the client or privacy impact.
3Recommend a direction rather than writing replacement code.
4Prioritize no more than four findings.

Learning objectives

• Interpret remaining quota after the current request
• Distinguish absolute HTTP times from retry durations
• Keep internal rate-limit identity out of public metadata

src/rate-limit-headers.tsTypeScript

@@ -0,0 +1,27 @@

1+export interface RateLimitDecision {

2+ readonly actorId: string;

3+ readonly limit: number;

4+ readonly usedBeforeRequest: number;

5+ readonly allowed: boolean;

6+ readonly resetAtMs: number;

7+}

9+export function buildRateLimitHeaders(

10+ decision: RateLimitDecision,

11+ nowMs: number,

12+): Readonly<Record<string, string>> {

13+ const headers: Record<string, string> = {

14+ "RateLimit-Limit": String(decision.limit),

15+ "RateLimit-Remaining": String(

16+ decision.limit - decision.usedBeforeRequest,

17+ ),

18+ "RateLimit-Reset": String(decision.resetAtMs),

19+ "X-RateLimit-Actor": decision.actorId,

20+ };

21+

22+ if (!decision.allowed && decision.resetAtMs > nowMs) {

23+ headers["Retry-After"] = String(decision.resetAtMs);

24+ }

25+

26+ return headers;

27+}

Reference solution

The findings below are ordered by priority.

Findings

1. Remaining quota does not account for the current request

Location: src/rate-limit-headers.ts:13-17

For an allowed request, the helper reports limit - usedBeforeRequest, which is the capacity before consuming that request. The value is one too high. If a denied decision arrives after the counter has exceeded the limit, the same subtraction can also expose a negative remaining count instead of the required zero.

For allowed decisions, subtract the current request as well; for denied decisions, return zero. Clamp the public value at zero defensively.

2. The reset header publishes milliseconds as though they were seconds

Location: src/rate-limit-headers.ts:18

RateLimit-Reset requires an absolute Unix timestamp in seconds, but the code emits resetAtMs unchanged. Clients interpret a value one thousand times too large and may believe the window resets far in the future.

Divide by 1,000 and round up before converting the reset timestamp to a string.

3. Retry-After is an absolute millisecond timestamp, not a duration

Location: src/rate-limit-headers.ts:22-24

On a denied request, the code copies the window timestamp into Retry-After. The contract requires seconds from now until reset, so a conforming client can wait for an effectively unbounded duration.

Compute resetAtMs - nowMs, convert the difference to seconds with upward rounding, and enforce the documented minimum of one second.

4. A public header discloses the internal actor identifier

Location: src/rate-limit-headers.ts:19

X-RateLimit-Actor exposes an internal identity value on every response. That identifier is not part of the client contract and can leak account topology or user identifiers through browsers, logs, and intermediary caches.

Remove the actor header entirely; identity remains an internal input used by the limiter, not response metadata.

Reasonable non-findings

Returning a plain string record is sufficient for the HTTP adapter.
RateLimit-Limit is emitted from the correct decision field.
The helper may rely on the limiter's stated consistency guarantees for allowed and usedBeforeRequest.