diff --git a/src/content/docs/troubleshooting/troubleshooting.mdx b/src/content/docs/troubleshooting/troubleshooting.mdx
index 6f4f74a6..03b2034b 100644
--- a/src/content/docs/troubleshooting/troubleshooting.mdx
+++ b/src/content/docs/troubleshooting/troubleshooting.mdx
@@ -149,6 +149,12 @@ If you are getting a "command not found" error, try the following:
 - **500 Internal Server Error:** Check the application logs for detailed error information.
 - **Health endpoint failures:** Start with `GET /api/v1/health/ready` for standard readiness checks. Use `GET /api/v1/health/live` for process-alive checks, and use authenticated `GET /api/v1/health` only when you intentionally configured `HEALTH_CHECK_TOKEN`.
 
+### Rate Limiting & Timeouts
+
+- **429 Too Many Requests:** The client IP has exceeded the rate limit. Check the `RATE_LIMIT_MAX_REQUESTS` and `RATE_LIMIT_WINDOW_SECONDS` settings. The response includes a `Retry-After` header indicating how many seconds to wait before retrying.
+- **503 Service Unavailable:** The server is busy or the request timed out at the rack/server layer (e.g. `RACK_TIMEOUT_SERVICE_TIMEOUT`). Returns a `Retry-After` header matching `RETRY_AFTER_TIMEOUT_SECONDS`.
+- **504 Gateway Timeout:** The target website or scraper took too long to respond (exceeding `HTML2RSS_TOTAL_TIMEOUT_SECONDS`).
+
 ### Feed Problems
 
 - Try a more specific listing, newsroom, changelog, or updates URL before changing infrastructure
diff --git a/src/content/docs/web-application/reference/env-variables.mdx b/src/content/docs/web-application/reference/env-variables.mdx
index b2e5ca2d..eb01a0aa 100644
--- a/src/content/docs/web-application/reference/env-variables.mdx
+++ b/src/content/docs/web-application/reference/env-variables.mdx
@@ -18,6 +18,11 @@ description: "Configuration reference for html2rss-web environment variables."
 | `AUTO_SOURCE_ENABLED`             | `true` by default in development/test, `false` otherwise                                                                                                     |
 | `ASYNC_FEED_REFRESH_ENABLED`      | optional boolean; default `false`                                                                                                                            |
 | `ASYNC_FEED_REFRESH_STALE_FACTOR` | optional integer `>= 1`; default `3`                                                                                                                         |
+| `FEEDS_CACHE_MAX_SIZE`            | optional integer `>= 1`; default `500`; maximum number of feeds to cache in memory before eviction                                                           |
+| `RATE_LIMIT_ENABLED`              | optional boolean; default `true` (except `false` in `test`); enables or disables client IP rate limiting                                                     |
+| `RATE_LIMIT_MAX_REQUESTS`         | optional integer `>= 1`; default `60`; maximum requests allowed per IP per window                                                                            |
+| `RATE_LIMIT_WINDOW_SECONDS`       | optional integer `>= 1`; default `60`; rate limiter sliding window duration in seconds                                                                       |
+| `RETRY_AFTER_TIMEOUT_SECONDS`     | optional integer `>= 1`; default `300`; Retry-After header backoff duration returned on timeouts                                                             |
 | `PORT`                            | app listen port; compose uses `4000`                                                                                                                         |
 | `RACK_ENV`                        | Rack environment; quickstart uses `development`, production examples use `production`                                                                        |
 | `RACK_TIMEOUT_SERVICE_TIMEOUT`    | optional; total web-request timeout in seconds; default `30`                                                                                                 |