diff --git a/public/openapi.json b/public/openapi.json
index 13dd684..218a85e 100644
--- a/public/openapi.json
+++ b/public/openapi.json
@@ -3,7 +3,7 @@
   "info": {
     "title": "DocFast API",
     "version": "1.0.0",
-    "description": "Convert HTML, Markdown, and URLs to pixel-perfect PDFs. Built-in invoice & receipt templates.\n\n## Authentication\nAll conversion and template endpoints require an API key via `Authorization: Bearer <key>` or `X-API-Key: <key>` header.\n\n## Demo Endpoints\nTry the API without signing up! Demo endpoints are public (no API key needed) but rate-limited to 5 requests/hour per IP and produce watermarked PDFs.\n\n## Rate Limits\n- Demo: 5 PDFs/hour per IP (watermarked)\n- Pro tier: 5,000 PDFs/month, 30 req/min\n\n## Getting Started\n1. Try the demo at `POST /v1/demo/html` — no signup needed\n2. Subscribe to Pro at [docfast.dev](https://docfast.dev/#pricing) for clean PDFs\n3. Use your API key to convert documents",
+    "description": "Convert HTML, Markdown, and URLs to pixel-perfect PDFs. Built-in invoice & receipt templates.\n\n## Authentication\nAll conversion and template endpoints require an API key via `Authorization: Bearer <key>` or `X-API-Key: <key>` header.\n\n## Demo Endpoints\nTry the API without signing up! Demo endpoints are public (no API key needed) but rate-limited to 5 requests/hour per IP and produce watermarked PDFs.\n\n## Rate Limits\n- Demo: 5 PDFs/hour per IP (watermarked)\n- Pro tier: 5,000 PDFs/month, 30 req/min\n\nAll rate-limited endpoints return `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. On `429`, a `Retry-After` header indicates seconds until the next allowed request.\n\n## Getting Started\n1. Try the demo at `POST /v1/demo/html` — no signup needed\n2. Subscribe to Pro at [docfast.dev](https://docfast.dev/#pricing) for clean PDFs\n3. Use your API key to convert documents",
     "contact": {
       "name": "DocFast",
       "url": "https://docfast.dev",
@@ -56,6 +56,36 @@
         "description": "API key via X-API-Key header"
       }
     },
+    "headers": {
+      "X-RateLimit-Limit": {
+        "description": "The maximum number of requests allowed in the current time window",
+        "schema": {
+          "type": "integer",
+          "example": 30
+        }
+      },
+      "X-RateLimit-Remaining": {
+        "description": "The number of requests remaining in the current time window",
+        "schema": {
+          "type": "integer",
+          "example": 29
+        }
+      },
+      "X-RateLimit-Reset": {
+        "description": "Unix timestamp (seconds since epoch) when the rate limit window resets",
+        "schema": {
+          "type": "integer",
+          "example": 1679875200
+        }
+      },
+      "Retry-After": {
+        "description": "Number of seconds to wait before retrying the request (returned on 429 responses)",
+        "schema": {
+          "type": "integer",
+          "example": 60
+        }
+      }
+    },
     "schemas": {
       "PdfOptions": {
         "type": "object",
diff --git a/scripts/generate-openapi.mjs b/scripts/generate-openapi.mjs
index 3997b3c..dd4085f 100644
--- a/scripts/generate-openapi.mjs
+++ b/scripts/generate-openapi.mjs
@@ -29,6 +29,8 @@ Try the API without signing up! Demo endpoints are public (no API key needed) bu
 - Demo: 5 PDFs/hour per IP (watermarked)
 - Pro tier: 5,000 PDFs/month, 30 req/min
 
+All rate-limited endpoints return \`X-RateLimit-Limit\`, \`X-RateLimit-Remaining\`, and \`X-RateLimit-Reset\` headers. On \`429\`, a \`Retry-After\` header indicates seconds until the next allowed request.
+
 ## Getting Started
 1. Try the demo at \`POST /v1/demo/html\` — no signup needed
 2. Subscribe to Pro at [docfast.dev](https://docfast.dev/#pricing) for clean PDFs
@@ -64,6 +66,36 @@ Try the API without signing up! Demo endpoints are public (no API key needed) bu
           description: 'API key via X-API-Key header'
         }
       },
+      headers: {
+        'X-RateLimit-Limit': {
+          description: 'The maximum number of requests allowed in the current time window',
+          schema: {
+            type: 'integer',
+            example: 30
+          }
+        },
+        'X-RateLimit-Remaining': {
+          description: 'The number of requests remaining in the current time window',
+          schema: {
+            type: 'integer',
+            example: 29
+          }
+        },
+        'X-RateLimit-Reset': {
+          description: 'Unix timestamp (seconds since epoch) when the rate limit window resets',
+          schema: {
+            type: 'integer',
+            example: 1679875200
+          }
+        },
+        'Retry-After': {
+          description: 'Number of seconds to wait before retrying the request (returned on 429 responses)',
+          schema: {
+            type: 'integer',
+            example: 60
+          }
+        }
+      },
       schemas: {
         PdfOptions: {
           type: 'object',