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[2]: Choose cache policy for an API or a static asset.,Debug a response that is stale or revalidated too often.
  caveats[2]: These are response examples; request directives can have different effects.,Extensions depend on the cache implementation.
  related[2]: 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[3]{title,url}:
    IETF HTTP caching,"https://httpwg.org/specs/rfc9111.html"
    RFC 8246 immutable responses,"https://httpwg.org/specs/rfc8246.html"
    RFC 5861 cache extensions,"https://www.rfc-editor.org/rfc/rfc5861.html"
  reading[1]: 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[4]{section,field,type,example}:
    data,directive,string,max-age
    data,example,string,max-age=300
    data,use,string,Permit reuse while the response is fresh for 30…
    data,pitfall,string,Age already spent in an upstream cache counts t…
data[12]{directive,example,use,pitfall}:
  max-age,max-age=300,Permit reuse while the response is fresh for 300 seconds.,Age already spent in an upstream cache counts toward freshness.
  s-maxage,s-maxage=60,Set freshness for shared caches separately from browsers.,It does not set a browser-only lifetime.
  no-cache,no-cache,Store a response but validate it before reuse.,The name does not mean do not store.
  no-store,no-store,Ask caches not to retain this request or response.,It does not erase copies stored before this response.
  private,private,Keep a personalized response out of shared caches.,A browser may still store it.
  public,"public, max-age=600",Explicitly permit shared-cache storage under HTTP rules.,Do not expose user-specific content.
  must-revalidate,must-revalidate,Require validation after freshness expires.,It does not force validation while fresh.
  proxy-revalidate,proxy-revalidate,Apply the stale-validation requirement to shared caches.,Private browser caches are outside this directive.
  no-transform,no-transform,Ask intermediaries to preserve the representation.,Compression and media pipelines need their own testing.
  immutable,"public, max-age=31536000, immutable",Avoid revalidation during freshness for versioned assets.,Change the URL when the asset bytes change.
  stale-while-revalidate,"max-age=60, stale-while-revalidate=30",Allow a bounded stale response during background validation.,Support and CDN configuration vary.
  stale-if-error,"max-age=60, stale-if-error=600",Allow bounded stale reuse on eligible failures.,Not suitable for every correctness-sensitive response.