@devries-cameron20 / composio Mirror · read-only / commits / 6a3b76039
Fork 0

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(rate-limits): consolidate into the reference page, drop the duplicate /docs guide

Fold the guide content (platform vs upstream-provider 429s, backoff recipe, no-automated-suspension note, multi-tenant guidance) into the existing reference/rate-limits.mdx + its v3 copy. Remove the new docs/rate-limits.mdx and its nav entry. Single source of truth, no cross-page drift. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Palash Kala committed Jun 23, 2026 at 22:20 UTC 6a3b76039069fceebc76ab4a0cecb79cceec8f6d
4 files changed +112 -132
docs/content/docs/meta.json
-1
@@ -32,7 +32,6 @@
32 "proxy-execute",
33 "projects",
34 "observability",
35 - "rate-limits",
35 "signing-up-as-an-agent",
36 "common-faq",
37 "glossary",
docs/content/docs/rate-limits.mdx deleted
-105
@@ -1,105 +0,0 @@
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 | Custom |
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. Custom, higher-volume 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).
docs/content/reference/rate-limits.mdx
+56 -13
@@ -1,12 +1,17 @@
1 ---
2 title: Rate Limits
3 -description: Composio API rate limits by plan, rate limit headers, and best practices
4 -keywords: [API rate limits, rate limiting, throttling, 429 too many requests, API quotas, request limits]
3 +description: Composio API rate limits by plan, the headers to read, how to handle 429s, and how upstream provider limits differ
4 +keywords: [API rate limits, rate limiting, throttling, 429 too many requests, API quotas, request limits, suspension, multi-tenant, retry-after, x-ratelimit]
5 ---
6
7 -Rate limits are enforced **per organization** on a fixed one-minute window (aligned to the start of each minute). Your live limit is always returned in the `X-RateLimit` header; the table below lists the current defaults.
7 +There are two independent kinds of rate limit when you use Composio:
8
9 -## Rate limits by plan
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 +## Composio platform limits
13 +
14 +Rate limits are enforced **per organization** on a fixed one-minute window (aligned to the start of each minute), shared across all of your `userId`s, API keys, and endpoints. Your live limit is always returned in the `X-RateLimit` header; the table below lists the current defaults.
15
16 | Plan | Rate Limit | Window |
17 |------|------------|--------|
@@ -19,9 +24,9 @@ Rate limits are enforced **per organization** on a fixed one-minute window (alig
24 All authenticated API endpoints share your organization's rate limit. This includes tool execution, connected accounts, triggers, and all other API operations.
25 </Callout>
26
22 -## Rate limit headers
27 +### Rate limit headers
28
24 -API responses include headers to help you track your usage:
29 +Every response includes headers, so you never have to hardcode a number:
30
31 | Header | Description |
32 |--------|-------------|
@@ -30,9 +35,11 @@ API responses include headers to help you track your usage:
35 | `X-RateLimit-Window-Size` | Window size (e.g., `60s` for 60 seconds) |
36 | `Retry-After` | Seconds until the window resets (only on 429 responses) |
37
33 -## Rate limit response
38 +Treat these as the source of truth and drive your client off them.
39
35 -When you exceed the rate limit, you'll receive a `429 Too Many Requests` response:
40 +### When you exceed the limit
41 +
42 +You get an `HTTP 429 Too Many Requests` with a `Retry-After` header:
43
44 ```json
45 {
@@ -40,17 +47,53 @@ When you exceed the rate limit, you'll receive a `429 Too Many Requests` respons
47 }
48 ```
49
43 -## Best practices
50 +A `429` is a throttle, not a cutoff. The window auto-resets the next minute and you can continue; nothing about your account changes.
51 +
52 +### Will I get suspended for going over?
53 +
54 +<Callout type="info">
55 +**No.** Composio does not automatically suspend, review, or restrict accounts based on request volume, concurrency, or error rate. Exceeding your limit only returns `429` throttling that clears on the next minute. There is no automated abuse trigger.
56 +</Callout>
57 +
58 +The only hard block is a manual action by our team in rare cases (e.g. confirmed abuse), which returns `HTTP 403` with `Organization temporarily blocked. Please contact technical support.` It is never automatic, and support is the path to resolve it.
59 +
60 +### Handling 429s
61 +
62 +- Honor `Retry-After` first; otherwise wait for the window (`X-RateLimit-Window-Size`); otherwise fall back to exponential backoff with jitter, capping retries (e.g. 5) before surfacing an error.
63 +- Watch `X-RateLimit-Remaining` and slow down before you hit zero.
64 +- Cache tool definitions and other static data, batch where you can, and avoid tight polling loops.
65 +
66 +```python
67 +import time, random
68 +
69 +def with_backoff(make_request, max_retries=5):
70 + for attempt in range(max_retries):
71 + resp = make_request()
72 + if resp.status_code != 429:
73 + return resp
74 + retry_after = resp.headers.get("Retry-After")
75 + delay = float(retry_after) if retry_after else min(2 ** attempt, 30) + random.random()
76 + time.sleep(delay)
77 + raise RuntimeError("Composio rate limit: retries exhausted")
78 +```
79 +
80 +## Upstream provider limits
81 +
82 +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`, which Composio surfaces back to you.
83
45 -1. **Monitor your usage** - Check the `X-RateLimit-Remaining` header to track how close you are to the limit.
84 +The most common cause 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 (Slack in particular throttles non-Marketplace apps aggressively).
85 +
86 +<Callout type="warn">
87 +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.
88 +</Callout>
89
47 -2. **Implement backoff** - When you receive a `429`, wait for the duration specified in `Retry-After` before retrying.
90 +## High-volume and multi-tenant usage
91
49 -3. **Cache responses** - Cache tool definitions and other static data to reduce unnecessary API calls.
92 +For multi-tenant apps, the recommended pattern is one Composio account with a unique `userId` per end-user. You do not need per-tenant sub-accounts. 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.
93
94 ## Need higher limits?
95
53 -If you're hitting rate limits regularly, consider upgrading your plan or [talk to us](https://calendly.com/composiohq/enterprise) to discuss custom limits for your use case.
96 +If you're hitting rate limits regularly, [talk to us](https://calendly.com/composiohq/enterprise) to discuss custom limits for your use case. Custom, higher-volume limits come with the Enterprise plan.
97
98 <Cards>
99 <Card title="Errors" href="/reference/errors">
docs/content/reference/v3/rate-limits.mdx
+56 -13
@@ -1,12 +1,17 @@
1 ---
2 title: Rate Limits
3 -description: Composio API rate limits by plan, rate limit headers, and best practices
4 -keywords: [API rate limits, rate limiting, throttling, 429 too many requests, API quotas, request limits]
3 +description: Composio API rate limits by plan, the headers to read, how to handle 429s, and how upstream provider limits differ
4 +keywords: [API rate limits, rate limiting, throttling, 429 too many requests, API quotas, request limits, suspension, multi-tenant, retry-after, x-ratelimit]
5 ---
6
7 -Rate limits are enforced **per organization** on a fixed one-minute window (aligned to the start of each minute). Your live limit is always returned in the `X-RateLimit` header; the table below lists the current defaults.
7 +There are two independent kinds of rate limit when you use Composio:
8
9 -## Rate limits by plan
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 +## Composio platform limits
13 +
14 +Rate limits are enforced **per organization** on a fixed one-minute window (aligned to the start of each minute), shared across all of your `userId`s, API keys, and endpoints. Your live limit is always returned in the `X-RateLimit` header; the table below lists the current defaults.
15
16 | Plan | Rate Limit | Window |
17 |------|------------|--------|
@@ -19,9 +24,9 @@ Rate limits are enforced **per organization** on a fixed one-minute window (alig
24 All authenticated API endpoints share your organization's rate limit. This includes tool execution, connected accounts, triggers, and all other API operations.
25 </Callout>
26
22 -## Rate limit headers
27 +### Rate limit headers
28
24 -API responses include headers to help you track your usage:
29 +Every response includes headers, so you never have to hardcode a number:
30
31 | Header | Description |
32 |--------|-------------|
@@ -30,9 +35,11 @@ API responses include headers to help you track your usage:
35 | `X-RateLimit-Window-Size` | Window size (e.g., `60s` for 60 seconds) |
36 | `Retry-After` | Seconds until the window resets (only on 429 responses) |
37
33 -## Rate limit response
38 +Treat these as the source of truth and drive your client off them.
39
35 -When you exceed the rate limit, you'll receive a `429 Too Many Requests` response:
40 +### When you exceed the limit
41 +
42 +You get an `HTTP 429 Too Many Requests` with a `Retry-After` header:
43
44 ```json
45 {
@@ -40,17 +47,53 @@ When you exceed the rate limit, you'll receive a `429 Too Many Requests` respons
47 }
48 ```
49
43 -## Best practices
50 +A `429` is a throttle, not a cutoff. The window auto-resets the next minute and you can continue; nothing about your account changes.
51 +
52 +### Will I get suspended for going over?
53 +
54 +<Callout type="info">
55 +**No.** Composio does not automatically suspend, review, or restrict accounts based on request volume, concurrency, or error rate. Exceeding your limit only returns `429` throttling that clears on the next minute. There is no automated abuse trigger.
56 +</Callout>
57 +
58 +The only hard block is a manual action by our team in rare cases (e.g. confirmed abuse), which returns `HTTP 403` with `Organization temporarily blocked. Please contact technical support.` It is never automatic, and support is the path to resolve it.
59 +
60 +### Handling 429s
61 +
62 +- Honor `Retry-After` first; otherwise wait for the window (`X-RateLimit-Window-Size`); otherwise fall back to exponential backoff with jitter, capping retries (e.g. 5) before surfacing an error.
63 +- Watch `X-RateLimit-Remaining` and slow down before you hit zero.
64 +- Cache tool definitions and other static data, batch where you can, and avoid tight polling loops.
65 +
66 +```python
67 +import time, random
68 +
69 +def with_backoff(make_request, max_retries=5):
70 + for attempt in range(max_retries):
71 + resp = make_request()
72 + if resp.status_code != 429:
73 + return resp
74 + retry_after = resp.headers.get("Retry-After")
75 + delay = float(retry_after) if retry_after else min(2 ** attempt, 30) + random.random()
76 + time.sleep(delay)
77 + raise RuntimeError("Composio rate limit: retries exhausted")
78 +```
79 +
80 +## Upstream provider limits
81 +
82 +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`, which Composio surfaces back to you.
83
45 -1. **Monitor your usage** - Check the `X-RateLimit-Remaining` header to track how close you are to the limit.
84 +The most common cause 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 (Slack in particular throttles non-Marketplace apps aggressively).
85 +
86 +<Callout type="warn">
87 +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.
88 +</Callout>
89
47 -2. **Implement backoff** - When you receive a `429`, wait for the duration specified in `Retry-After` before retrying.
90 +## High-volume and multi-tenant usage
91
49 -3. **Cache responses** - Cache tool definitions and other static data to reduce unnecessary API calls.
92 +For multi-tenant apps, the recommended pattern is one Composio account with a unique `userId` per end-user. You do not need per-tenant sub-accounts. 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.
93
94 ## Need higher limits?
95
53 -If you're hitting rate limits regularly, consider upgrading your plan or [talk to us](https://calendly.com/composiohq/enterprise) to discuss custom limits for your use case.
96 +If you're hitting rate limits regularly, [talk to us](https://calendly.com/composiohq/enterprise) to discuss custom limits for your use case. Custom, higher-volume limits come with the Enterprise plan.
97
98 <Cards>
99 <Card title="Errors" href="/reference/v3/errors">