From 63d3960f79d3d82f38a50af6c7045c76806c954c Mon Sep 17 00:00:00 2001
From: "Wei S." <5291640+wayneshn@users.noreply.github.com>
Date: Thu, 4 Sep 2025 17:44:10 +0300
Subject: [PATCH] Adding rate limiting docs (#88)

Co-authored-by: Wayne <5291640+ringoinca@users.noreply.github.com>
---
 docs/.vitepress/config.mts |  1 +
 docs/api/rate-limiting.md  | 51 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 52 insertions(+)
 create mode 100644 docs/api/rate-limiting.md

diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 34d8d2c..001a9dc 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -71,6 +71,7 @@ export default defineConfig({
 				items: [
 					{ text: 'Overview', link: '/api/' },
 					{ text: 'Authentication', link: '/api/authentication' },
+					{ text: 'Rate Limiting', link: '/api/rate-limiting' },
 					{ text: 'Auth', link: '/api/auth' },
 					{ text: 'Archived Email', link: '/api/archived-email' },
 					{ text: 'Dashboard', link: '/api/dashboard' },
diff --git a/docs/api/rate-limiting.md b/docs/api/rate-limiting.md
new file mode 100644
index 0000000..12fa94e
--- /dev/null
+++ b/docs/api/rate-limiting.md
@@ -0,0 +1,51 @@
+# Rate Limiting
+
+The API implements rate limiting as a security measure to protect your instance from denial-of-service (DoS) and brute-force attacks. This is a crucial feature for maintaining the security and stability of the application.
+
+## How It Works
+
+The rate limiter restricts the number of requests an IP address can make within a specific time frame. These limits are configurable via environment variables to suit your security needs.
+
+By default, the limits are:
+
+- **100 requests** per **15 minutes** per IP address.
+
+If this limit is exceeded, the API will respond with an HTTP `429 Too Many Requests` status code.
+
+### Response Body
+
+When an IP address is rate-limited, the API will return a JSON response with the following format:
+
+```json
+{
+	"status": 429,
+	"message": "Too many requests from this IP, please try again after 15 minutes"
+}
+```
+
+## Configuration
+
+You can customize the rate-limiting settings by setting the following environment variables in your `.env` file:
+
+- `RATE_LIMIT_WINDOW_MS`: The time window in milliseconds. Defaults to `900000` (15 minutes).
+- `RATE_LIMIT_MAX_REQUESTS`: The maximum number of requests allowed per IP address within the time window. Defaults to `100`.
+
+## Handling Rate Limits
+
+If you are developing a client that interacts with the API, you should handle rate limiting gracefully:
+
+1.  **Check the Status Code**: Monitor for a `429` HTTP status code in responses.
+2.  **Implement a Retry Mechanism**: When you receive a `429` response, it is best practice to wait before retrying the request. Implementing an exponential backoff strategy is recommended.
+3.  **Check Headers**: The response will include the following standard headers to help you manage your request rate:
+    - `RateLimit-Limit`: The maximum number of requests allowed in the current window.
+    - `RateLimit-Remaining`: The number of requests you have left in the current window.
+    - `RateLimit-Reset`: The time when the rate limit window will reset, in UTC epoch seconds.
+
+## Excluded Endpoints
+
+Certain essential endpoints are excluded from rate limiting to ensure the application's UI remains responsive. These are:
+
+- `/auth/status`
+- `/settings/system`
+
+These endpoints can be called as needed without affecting your rate limit count.