# secondsUntilRetryAfter

:::caution[Unreleased]
Not in `@northguild/gmt` 1.20.0 on npm yet. It is on `main` and ships in the next release.
:::

## Signature

```ts
secondsUntilRetryAfter(value: string): number | null
```

Return the whole seconds to wait from a `Retry-After` header value.

- Takes the header's value: `Retry-After = HTTP-date / delay-seconds` (RFC 9110 section 10.2.3), and `delay-seconds = 1*DIGIT`.
- Digits are returned as they are, leading zeros allowed, without reading the clock. A value past the largest safe integer returns null.
- An HTTP-date is read through `parseHttpDate` (all three formats) and measured from now, rounded up to a whole second so a wait never falls short.
- **A past HTTP date gives a negative number.** Check `null` first, then wait `Math.max(0, n)`: `Math.max(0, null)` is 0, so an unchecked garbage value means "retry now".
- **A `:60` leap second returns null**, though RFC 9110 section 5.6.7 allows it (its `time-of-day` comment reads "00:00:00 - 23:59:60 (leap second)"): GMT's `parseHttpDate` refuses every second above 59.
- `null` is invalid input only: an empty or unparsable string such as `"soon"`, a sign, a space, a fraction, non-ASCII digits, digits past the largest safe integer, a non-string, or an HTTP-date with a `:60` second.
- No `timeZone`: an HTTP-date is always GMT.

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `value` | `string` | the header's value: digits, or an HTTP-date |

## Returns

the seconds to wait, negative for a past date, or null for anything else

## Examples

```ts
import { secondsUntilRetryAfter } from "@northguild/gmt/utc/calculate";

secondsUntilRetryAfter("120") // 120 (delay-seconds)
```

## Source

[utc/calculate/secondsUntilRetryAfter.ts](https://github.com/northguild/gmt/blob/main/packages/gmt/src/utc/calculate/secondsUntilRetryAfter.ts)