# Rate Limit Headers

> API rate limit headers with limit, remaining, reset, and retry-after.

- Name: `rate-limit-headers`
- Categories: api
- Detail page: https://open-types.dev/types/rate-limit-headers

## Install

```bash
# Types only
npx shadcn add @open-types/rate-limit-headers

# Types + Zod v4 validators
npx shadcn add @open-types/rate-limit-headers-zod

# Types + real-world examples
npx shadcn add @open-types/rate-limit-headers-examples
```

## Types

```typescript
export interface RateLimitHeaders {
  limit: number;
  remaining: number;
  reset: number;
  retry_after?: number;
}
```

## Zod validator

```typescript
import * as z from "zod";
import type { RateLimitHeaders } from "../types/rate-limit-headers";

export const rateLimitHeadersSchema = z.object({
  limit: z.number().int().min(0, { error: "Limit must be greater than or equal to 0" }),
  remaining: z
    .number()
    .int()
    .min(0, { error: "Remaining must be greater than or equal to 0" }),
  reset: z.number().int().gt(0, { error: "Reset must be greater than 0" }),
  retry_after: z.number().int().min(0).optional(),
}) satisfies z.ZodType<RateLimitHeaders>;

export type { RateLimitHeaders } from "../types/rate-limit-headers";
```

## Examples

```typescript
// Source: https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-ratelimit-headers
// Captured: 2026-05
import type { RateLimitHeaders } from "../types/rate-limit-headers";

export const rateLimitHeadersExamples = {
  underLimit: {
    limit: 100,
    remaining: 42,
    reset: 1712948460,
  } satisfies RateLimitHeaders,
  exhausted: {
    limit: 100,
    remaining: 0,
    reset: 1712948460,
    retry_after: 60,
  } satisfies RateLimitHeaders,
  burstQuota: {
    limit: 1000,
    remaining: 999,
    reset: 1712948700,
  } satisfies RateLimitHeaders,
  oneRemaining: {
    limit: 60,
    remaining: 1,
    reset: 1712948460,
  } satisfies RateLimitHeaders,
} as const;
```