HTTP Cache-Control Directives
Cache-Control directives for browser and shared caches, with example values, intended behavior, and common configuration mistakes.
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 it when
- Choose cache policy for an API or a static asset.
- Debug a response that is stale or revalidated too often.
Watch out for
- These are response examples; request directives can have different effects.
- Extensions depend on the cache implementation.
The data
12 rows
| 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. |
Fields
The shape of this dataset, read from the data itself: every column, its type and a real value. Agents can use this to plan a query without fetching the whole document.
| 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… |
Fetch the same bytes
The static files contain the same reference rows as the API, with no API rate limit. Live metadata, such as view counts, may differ. Use the API for content negotiation; use the static files for a cacheable snapshot.
curl "https://yjtoon.com/api/dataset/http-cache-directives?format=toon"
const res = await fetch( "https://yjtoon.com/static-data/dataset/http-cache-directives.toon" ); const toon = await res.text();
Rate limit: 120 requests per minute per IP, no key and no signup. API reference →
Sources and editorial notes
Original editorial reference notes by YJTOON, informed by the linked primary documentation. External specifications retain their own licenses.
Editorial review: . Source documents keep their own licenses.