api: YAML JSON TOON Database
version: 1.0.0
format: json
dataset:
  id: 1001
  slug: http-cache-directives
  title: HTTP Cache-Control Directives
  description: Cache-Control directives for browser and shared caches, with example values, intended behavior, and common configuration mistakes.
  summary: Cache-Control directives for browser and shared caches, with example values, intended behavior, and common configuration mistakes. Each row includes a practical application and a failure to check before using it.
  use_when:
    - Choose cache policy for an API or a static asset.
    - Debug a response that is stale or revalidated too often.
  caveats:
    - These are response examples; request directives can have different effects.
    - Extensions depend on the cache implementation.
  related:
    - http-conditional-requests
    - http-response-headers
  category: HTTP Status Codes
  category_slug: http-status-codes
  tags: http-status-codes,http cache directives,reference,engineering
  view_count: 0
  created_at: 1791798640
  updated_at: 1791798640
  reviewed_at: "2026-10-12"
  sources:
    - title: IETF HTTP caching
      url: "https://httpwg.org/specs/rfc9111.html"
    - title: RFC 8246 immutable responses
      url: "https://httpwg.org/specs/rfc8246.html"
    - title: RFC 5861 cache extensions
      url: "https://www.rfc-editor.org/rfc/rfc5861.html"
  reading:
    - http-caching-with-etags-and-cache-control
  provenance: Original editorial reference notes by YJTOON, informed by the linked primary documentation. External specifications retain their own licenses.
  entry_count: 12
  fields:
    - section: data
      field: directive
      type: string
      example: max-age
    - section: data
      field: example
      type: string
      example: max-age=300
    - section: data
      field: use
      type: string
      example: Permit reuse while the response is fresh for 30…
    - section: data
      field: pitfall
      type: string
      example: Age already spent in an upstream cache counts t…
data:
  - directive: max-age
    example: max-age=300
    use: Permit reuse while the response is fresh for 300 seconds.
    pitfall: Age already spent in an upstream cache counts toward freshness.
  - directive: s-maxage
    example: s-maxage=60
    use: Set freshness for shared caches separately from browsers.
    pitfall: It does not set a browser-only lifetime.
  - directive: no-cache
    example: no-cache
    use: Store a response but validate it before reuse.
    pitfall: The name does not mean do not store.
  - directive: no-store
    example: no-store
    use: Ask caches not to retain this request or response.
    pitfall: It does not erase copies stored before this response.
  - directive: private
    example: private
    use: Keep a personalized response out of shared caches.
    pitfall: A browser may still store it.
  - directive: public
    example: public, max-age=600
    use: Explicitly permit shared-cache storage under HTTP rules.
    pitfall: Do not expose user-specific content.
  - directive: must-revalidate
    example: must-revalidate
    use: Require validation after freshness expires.
    pitfall: It does not force validation while fresh.
  - directive: proxy-revalidate
    example: proxy-revalidate
    use: Apply the stale-validation requirement to shared caches.
    pitfall: Private browser caches are outside this directive.
  - directive: no-transform
    example: no-transform
    use: Ask intermediaries to preserve the representation.
    pitfall: Compression and media pipelines need their own testing.
  - directive: immutable
    example: public, max-age=31536000, immutable
    use: Avoid revalidation during freshness for versioned assets.
    pitfall: Change the URL when the asset bytes change.
  - directive: stale-while-revalidate
    example: max-age=60, stale-while-revalidate=30
    use: Allow a bounded stale response during background validation.
    pitfall: Support and CDN configuration vary.
  - directive: stale-if-error
    example: max-age=60, stale-if-error=600
    use: Allow bounded stale reuse on eligible failures.
    pitfall: Not suitable for every correctness-sensitive response.