From 1f5bb5c8e253411a511719252c0ca1777b79b023 Mon Sep 17 00:00:00 2001
From: Thomas Bonnin <233326+TBonnin@users.noreply.github.com>
Date: Mon, 11 Mar 2024 11:33:38 +0100
Subject: [PATCH] Add rate limits info to docs (#1836)

## Describe your changes
Adding docs to describe global rate limiting

## Issue ticket number and link
https://linear.app/nango/issue/NAN-536/document-global-rate-limit
---
 docs-v2/mint.json                     |  1 +
 docs-v2/reference/api/rate-limits.mdx | 13 +++++++++++++
 docs-v2/reference/sdks/node.mdx       | 23 +++++++++++++++++++++++
 3 files changed, 37 insertions(+)
 create mode 100644 docs-v2/reference/api/rate-limits.mdx

diff --git a/docs-v2/mint.json b/docs-v2/mint.json
index d4fc1986b1..b792d65fa1 100644
--- a/docs-v2/mint.json
+++ b/docs-v2/mint.json
@@ -476,6 +476,7 @@
                     "icon": "cloud",
                     "pages": [
                         "reference/api/authentication",
+                        "reference/api/rate-limits",
                         {
                             "group": "Integrations",
                             "pages": [
diff --git a/docs-v2/reference/api/rate-limits.mdx b/docs-v2/reference/api/rate-limits.mdx
new file mode 100644
index 0000000000..f1e76cf026
--- /dev/null
+++ b/docs-v2/reference/api/rate-limits.mdx
@@ -0,0 +1,13 @@
+---
+title: 'Rate limits'
+---
+
+The Nango API is rate-limited to prevent abuse and ensure fair usage across all clients. The rate limit is enforced on a per-account basis, with a fixed window of time and a maximum number of requests allowed within that window.
+
+Those headers are sent back with every API response:
+- `X-RateLimit-Limit` indicates the maximum number of requests a client can make within the rate limit window.
+- `X-RateLimit-Remaining` shows how many requests are remaining before the limit is reached.
+- `X-RateLimit-Reset` provides a Unix timestamp representing the time at which the current rate limit window resets, and the remaining request count is replenished.
+
+If a client exceeds the rate limit, the API will respond with a 429 `Too Many Requests` status code. In this case, the `Retry-After` header is included, indicating the number of seconds the client should wait before making another request to avoid being rate-limited.
+
diff --git a/docs-v2/reference/sdks/node.mdx b/docs-v2/reference/sdks/node.mdx
index 09a082ae20..07f59785bb 100644
--- a/docs-v2/reference/sdks/node.mdx
+++ b/docs-v2/reference/sdks/node.mdx
@@ -38,6 +38,29 @@ const nango = new Nango({ secretKey: '<SECRET-KEY>' });
   </ResponseField>
 </Expandable>
 
+# Rate limits
+
+The Nango SDK is rate-limited to prevent abuse and ensure fair usage across all clients. The rate limit is enforced on a per-account basis, with a fixed window of time and a maximum number of requests allowed within that window.
+
+If a client exceeds the rate limit, the API will respond with a 429 `Too Many Requests` status code. In this case, the `Retry-After` header is included, indicating the number of seconds the client should wait before making another request to avoid being rate-limited.
+
+To handle rate limiting gracefully, clients should monitor for the 429 status code and honor the `Retry-After` header value provided in the response.
+
+```js
+// Example:
+try {
+    const res = await nango.listIntegrations();
+    ...
+} catch(err) {
+    if (err.response.status === 429) {
+        const retryAfter = err.response.headers['retry-after'];
+        // wait and retry
+        ...
+    }
+    ...
+}
+```
+
 # Integrations
 
 ### List all integrations