Parse rate-limit response headers and calculate reset time

This parser accepts a limit, remaining count, reset value, and explicit current time, then returns normalized numeric values and the number of whole seconds until requests become available again. It recognizes common Unix-second and Unix-millisecond timestamps, strict UTC ISO 8601 timestamps, and short numeric reset offsets. Because the current time is supplied rather than read from a clock, the same input always produces the same result in tests, browser tools, queues, and API integrations.

Normalize response headers before scheduling retries

APIs commonly expose a maximum request count, a remaining count, and a reset value, but client code still has to turn those strings into a safe retry decision. Paste or pass the three header values as limit, remaining, and reset, then provide current_time for the instant at which the response was received. The parser validates that limit and remaining are non-negative integers and rejects a remaining value larger than the stated limit. It preserves the original reset text, reports whether it interpreted that value as an absolute timestamp or a seconds offset, and produces a normalized Unix reset time. The seconds_until_reset field is rounded upward to a whole second so a caller does not retry during the final fraction of a waiting interval. If the reset moment is already in the past, the wait is zero rather than negative. That output is suitable for logs, retry middleware, queue delay calculations, and test fixtures without requiring every integration to repeat the same parsing and boundary rules.

Understand how timestamps and offsets are distinguished

Numeric reset values are interpreted using conventions found in rate-limit response headers. Values of at least one billion are treated as Unix seconds, while values of at least one hundred billion are treated as Unix milliseconds and converted to seconds. Smaller non-negative numbers are seconds offsets added to current_time. This makes familiar values such as 30 or 900 behave as retry delays while contemporary epoch timestamps remain absolute. A reset may also be a strict ISO 8601 UTC value such as 2026-07-25T12:01:00Z, with optional milliseconds. The explicit UTC suffix avoids hidden timezone assumptions. current_time accepts the same absolute Unix-second, Unix-millisecond, or UTC ISO forms, but it is never treated as an offset. Calendar validation catches impossible dates, invalid clock fields, missing values, negative numbers, and unrelated strings. Most importantly, an unparseable reset is returned as an invalid-input error instead of being silently replaced with zero, because an accidental immediate retry can amplify throttling and prolong an outage.

Use deterministic output in clients and automated tests

A retry policy should separate parsing from policy decisions. Use this capability to establish the quota facts, then let your application decide whether to sleep, enqueue work, reduce concurrency, or surface a message. Supplying current_time is intentional: no system clock, network request, locale setting, or random value can change the answer. That property lets a browser calculation match an API calculation and makes regression fixtures stable months later. For example, a reset offset of 60 paired with a current time at exactly noon always produces a reset timestamp one minute later and sixty seconds remaining. Absolute reset times that precede the supplied current time produce zero seconds, which is useful when processing delayed webhook deliveries or archived response logs. The parser does not infer vendor-specific headers, perform requests, or choose exponential backoff parameters. It handles the standard values you already extracted and returns a compact result. The browser version is free, while automated API calls use the displayed base price of $0.002 per item.