On this page

Rate Limit Headers

Configure which rate limit response headers hitlimit sends with each request using the headers option.

HeadersConfig

The headers option accepts a HeadersConfig object with three boolean fields:

FieldTypeDefaultHeaders emitted
standardbooleantrueRateLimit-Limit, RateLimit-Remaining, RateLimit-Reset
legacybooleanfalseX-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
retryAfterbooleanfalseRetry-After (only on 429 responses)

Standard Headers (IETF)

Enable standard headers using the IETF RateLimit-* naming (no X- prefix):

hitlimit({
  limit: 100,
  window: '1m',
  headers: { standard: true }
})

// Each response includes:
// RateLimit-Limit: 100
// RateLimit-Remaining: 95
// RateLimit-Reset: 1706284860  (Unix timestamp)

Legacy Headers

Enable legacy X-RateLimit-* headers for compatibility with older clients:

hitlimit({
  limit: 100,
  window: '1m',
  headers: { legacy: true }
})

// Each response includes:
// X-RateLimit-Limit: 100
// X-RateLimit-Remaining: 95
// X-RateLimit-Reset: 1706284860

Retry-After Header

Enable Retry-After to tell rate-limited clients how many seconds to wait. Only sent on 429 responses:

hitlimit({
  limit: 100,
  window: '1m',
  headers: { retryAfter: true }
})

// On 429 responses only:
// Retry-After: 42  (seconds until window resets)

Combining Headers

Enable any combination of the three fields:

hitlimit({
  limit: 100,
  window: '1m',
  headers: {
    standard: true,    // RateLimit-* (IETF)
    legacy: true,      // X-RateLimit-* (legacy)
    retryAfter: true  // Retry-After on 429
  }
})

Disable All Headers

Omit the headers option entirely — no rate limit headers are sent by default unless you enable them:

hitlimit({
  limit: 100,
  window: '1m'
  // headers omitted — no rate limit headers sent
})

Ban Headers

When a client is banned (via ban.threshold), two additional headers are always included regardless of the headers config:

HeaderValue
X-RateLimit-Bantrue
X-RateLimit-Ban-ExpiresUnix timestamp when the ban expires