diff --git a/markdown/limitations.md b/markdown/limitations.md
new file mode 100644
index 0000000..7b3bd5a
--- /dev/null
+++ b/markdown/limitations.md
@@ -0,0 +1,15 @@
+# Limitations
+
+api.global is deplyoing a few hard limitations on a per account basis:
+
+* 1 million API requests per hour
+* 12 million API requests per day
+
+!!! hint
+    running into one of those limitations will result in a 429 status code with an info of when to try again attached as json payload in the response.
+
+    ```json
+    {
+      "retryIn": 3600000
+    }
+    ```
diff --git a/mkdocs.yml b/mkdocs.yml
index fb8c921..e218add 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -88,5 +88,6 @@ markdown_extensions:
 nav:
   - Overview:
     - Getting Started: index.md
+    - Limitations: limitations.md
     - NodeJS: nodejs.md
     - Support: support.md