Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 19:45 UTC
docs: add Rate limits & usage page
Per-org platform limits (window + headers + 429 backoff), the no-automated-suspension guarantee, upstream provider 429s + BYO-OAuth guidance, multi-tenant pattern, and the increase/SLA paths. Verified against apps/apollo/src/lib/ratelimit. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Palash Kala committed
Jun 23, 2026 at 21:55 UTC
0864f9821b06f84de46145f2780389149ab9ddc4
2 files changed
+106
docs/content/docs/meta.json
+1
@@ -32,6 +32,7 @@
32
"proxy-execute",
33
"projects",
34
"observability",
35
+ "rate-limits",
36
"signing-up-as-an-agent",
37
"common-faq",
38
"glossary",
docs/content/docs/rate-limits.mdx
new
+105
@@ -0,0 +1,105 @@
1
+---
2
+title: Rate limits & usage
3
+description: How Composio's API rate limits work, the headers to read, how to handle 429s, how upstream provider limits differ, and what to do for high-volume multi-tenant usage.
4
+keywords: [rate limit, rate limits, 429, too many requests, retry-after, x-ratelimit, throttling, quota, suspension, account suspended, abuse, high volume, multi-tenant, sla, status]
5
+---
6
+
7
+There are **two independent kinds of rate limit** when you use Composio, and most confusion comes from mixing them up:
8
+
9
+1. **Composio platform limits**: how many requests your organization can make to the Composio API per minute.
10
+2. **Upstream provider limits**: limits the *external* service (Gmail, Slack, Google Ads, etc.) enforces on the calls Composio makes on your behalf.
11
+
12
+This page covers both, plus how to handle `429`s and what to do for high-volume, multi-tenant workloads.
13
+
14
+## Composio platform rate limits
15
+
16
+Composio limits are applied **per organization**, on a **fixed one-minute window**, shared across all of your `userId`s, API keys, and endpoints (tool execution, connected accounts, triggers). The window resets at the start of each minute.
17
+
18
+### Read your limit from the response headers
19
+
20
+Your live limit is always returned on **every** response, so you never have to hardcode a number:
21
+
22
+| Header | Meaning |
23
+| --- | --- |
24
+| `X-RateLimit` | Your current request limit for the window |
25
+| `X-RateLimit-Remaining` | Requests remaining in the current window |
26
+| `X-RateLimit-Window-Size` | Window length, e.g. `60s` |
27
+
28
+Treat these headers as the source of truth and drive your client off them.
29
+
30
+### Default limits by plan
31
+
32
+These are the current **default** per-organization, per-minute ceilings. Your authoritative value is always `X-RateLimit` (limits can be raised for an account), but as an anchor for planning:
33
+
34
+| Plan | Requests per minute (per org) |
35
+| --- | --- |
36
+| Hobby / Starter | 2,000 |
37
+| Growth | 10,000 |
38
+| Enterprise | Effectively unlimited |
39
+
40
+### When you exceed the limit
41
+
42
+You get an **HTTP `429`** with a `Retry-After` header (seconds until the window resets):
43
+
44
+```json
45
+{ "message": "Rate limit exceeded. Limit: 2000 requests per 1 minutes" }
46
+```
47
+
48
+A `429` is a **throttle, not a cutoff**. The window auto-resets the next minute and you can continue, and nothing about your account changes.
49
+
50
+### Will I get suspended for going over?
51
+
52
+<Callout type="info">
53
+**No.** Composio does **not** automatically suspend, review, or restrict accounts based on request volume, concurrency, or error rates. Exceeding your limit only returns `429` throttling that clears on the next minute. There is no automated abuse trigger and no separate "account review" process.
54
+</Callout>
55
+
56
+The only hard block is a **manual** action by our team in rare cases (e.g. confirmed abuse). If that ever happens you'll receive an **HTTP `403`** with `Organization temporarily blocked. Please contact technical support.` It is never automatic, and support is the path to resolve it.
57
+
58
+### Handling 429s
59
+
60
+A small, well-behaved retry loop is all you need:
61
+
62
+- **Honor `Retry-After` first.** If it's present, wait that many seconds.
63
+- Otherwise wait for the window to roll over (`X-RateLimit-Window-Size`).
64
+- Otherwise fall back to **exponential backoff with jitter**, and cap retries (e.g. 5) before surfacing an error.
65
+- Watch `X-RateLimit-Remaining` and slow down *before* you hit zero.
66
+
67
+```python
68
+import time, random
69
+
70
+def with_backoff(make_request, max_retries=5):
71
+ for attempt in range(max_retries):
72
+ resp = make_request()
73
+ if resp.status_code != 429:
74
+ return resp
75
+ retry_after = resp.headers.get("Retry-After")
76
+ delay = float(retry_after) if retry_after else min(2 ** attempt, 30) + random.random()
77
+ time.sleep(delay)
78
+ raise RuntimeError("Composio rate limit: retries exhausted")
79
+```
80
+
81
+Other good practices: cache tool definitions and other static data, batch where you can, and avoid tight polling loops.
82
+
83
+## Upstream provider rate limits
84
+
85
+These are **separate** from Composio's limits. When Composio calls Gmail, Slack, Google Ads, etc. on your behalf, that provider enforces *its own* limits and can return `429` / `RESOURCE_EXHAUSTED`. Composio surfaces those errors back to you.
86
+
87
+The most common cause of provider `429`s in production is **Composio's shared managed auth**: many organizations connect through the same shared OAuth app, so you share that app's rate-limit bucket with everyone else (Slack in particular throttles non-Marketplace apps aggressively).
88
+
89
+<Callout type="warn">
90
+For production and high-volume workloads, use **your own OAuth app** via a [custom auth config](/docs/custom-app-vs-managed-app) instead of Composio-managed auth. Your own app gets its own isolated bucket and the provider's full per-app limits. Managed auth is best for development and prototyping.
91
+</Callout>
92
+
93
+## High-volume and multi-tenant usage
94
+
95
+If you run a multi-tenant app, the recommended pattern is **one Composio account with a unique `userId` per end-user**, exactly the single-key fan-out many teams already use. You do **not** need per-tenant sub-accounts; that adds complexity without raising your limit.
96
+
97
+To scale throughput, **move to a higher plan** (which raises your per-org limit) and use your own OAuth apps for the providers you call heavily, rather than splitting into multiple accounts.
98
+
99
+## Need a higher limit?
100
+
101
+Per-organization limits can be raised. If you're approaching your ceiling, [reach out](https://calendly.com/composiohq/enterprise) and we'll find the right limit for your workload. Higher-volume and unlimited limits come with the Enterprise plan.
102
+
103
+## Reliability & SLA
104
+
105
+A formal uptime SLA, support-response commitments, and a dedicated escalation contact are part of the **Enterprise** plan; [talk to us](https://calendly.com/composiohq/enterprise) if you need them. For security and compliance details, see [trust.composio.dev](https://trust.composio.dev).