@devries-cameron20 / composio-1 / commits / 568f32637
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.

docs(rate-limits): correct stale values in reference pages

Fixed 1-min window (was rolling 10-min), 2k/10k limits (was 20k/100k), Enterprise = Custom (was Unlimited), 60s window-size + 'per 1 minutes' 429. Reference pages kept in original terse form; v3 copies synced; index summaries updated. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Palash Kala committed Jun 23, 2026 at 22:25 UTC 568f32637ecf3c566e342c209f3215ec9fbe3d88
4 files changed +28 -114
docs/content/reference/index.mdx
+1 -1
@@ -10,7 +10,7 @@ Composio powers tool discovery, execution, authentication, and context managemen
10
11 - **Base URL**: <ApiBaseUrl />
12 - **[Authentication](/reference/authentication)**: `x-api-key` (project) or `x-org-api-key` (organization) header
13 -- **[Rate Limits](/reference/rate-limits)**: 2K-10K requests per minute per org; custom on Enterprise
13 +- **[Rate Limits](/reference/rate-limits)**: 2K-10K requests per minute (plan-dependent)
14
15 ## REST API
16
docs/content/reference/rate-limits.mdx
+13 -56
@@ -1,17 +1,12 @@
1 ---
2 title: Rate 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]
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]
5 ---
6
7 -There are two independent kinds of rate limit when you use Composio:
7 +Rate limits are enforced **per organization** on a fixed one-minute window.
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 -## 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.
9 +## Rate limits by plan
10
11 | Plan | Rate Limit | Window |
12 |------|------------|--------|
@@ -24,9 +19,9 @@ Rate limits are enforced **per organization** on a fixed one-minute window (alig
19 All authenticated API endpoints share your organization's rate limit. This includes tool execution, connected accounts, triggers, and all other API operations.
20 </Callout>
21
27 -### Rate limit headers
22 +## Rate limit headers
23
29 -Every response includes headers, so you never have to hardcode a number:
24 +API responses include headers to help you track your usage:
25
26 | Header | Description |
27 |--------|-------------|
@@ -35,11 +30,9 @@ Every response includes headers, so you never have to hardcode a number:
30 | `X-RateLimit-Window-Size` | Window size (e.g., `60s` for 60 seconds) |
31 | `Retry-After` | Seconds until the window resets (only on 429 responses) |
32
38 -Treat these as the source of truth and drive your client off them.
33 +## Rate limit response
34
40 -### When you exceed the limit
41 -
42 -You get an `HTTP 429 Too Many Requests` with a `Retry-After` header:
35 +When you exceed the rate limit, you'll receive a `429 Too Many Requests` response:
36
37 ```json
38 {
@@ -47,53 +40,17 @@ You get an `HTTP 429 Too Many Requests` with a `Retry-After` header:
40 }
41 ```
42
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.
43 +## Best practices
44
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>
45 +1. **Monitor your usage** - Check the `X-RateLimit-Remaining` header to track how close you are to the limit.
46
90 -## High-volume and multi-tenant usage
47 +2. **Honor `Retry-After`** - On a `429`, wait for the duration in the `Retry-After` header before retrying.
48
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.
49 +3. **Cache responses** - Cache tool definitions and other static data to reduce unnecessary API calls.
50
51 ## Need higher limits?
52
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.
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.
54
55 <Cards>
56 <Card title="Errors" href="/reference/errors">
docs/content/reference/v3/index.mdx
+1 -1
@@ -10,7 +10,7 @@ Composio powers tool discovery, execution, authentication, and context managemen
10
11 - **Base URL**: <ApiBaseUrl />
12 - **[Authentication](/reference/v3/authentication)**: `x-api-key` (project) or `x-org-api-key` (organization) header
13 -- **[Rate Limits](/reference/v3/rate-limits)**: 2K-10K requests per minute per org; custom on Enterprise
13 +- **[Rate Limits](/reference/v3/rate-limits)**: 2K-10K requests per minute (plan-dependent)
14
15 ## REST API
16
docs/content/reference/v3/rate-limits.mdx
+13 -56
@@ -1,17 +1,12 @@
1 ---
2 title: Rate 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]
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]
5 ---
6
7 -There are two independent kinds of rate limit when you use Composio:
7 +Rate limits are enforced **per organization** on a fixed one-minute window.
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 -## 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.
9 +## Rate limits by plan
10
11 | Plan | Rate Limit | Window |
12 |------|------------|--------|
@@ -24,9 +19,9 @@ Rate limits are enforced **per organization** on a fixed one-minute window (alig
19 All authenticated API endpoints share your organization's rate limit. This includes tool execution, connected accounts, triggers, and all other API operations.
20 </Callout>
21
27 -### Rate limit headers
22 +## Rate limit headers
23
29 -Every response includes headers, so you never have to hardcode a number:
24 +API responses include headers to help you track your usage:
25
26 | Header | Description |
27 |--------|-------------|
@@ -35,11 +30,9 @@ Every response includes headers, so you never have to hardcode a number:
30 | `X-RateLimit-Window-Size` | Window size (e.g., `60s` for 60 seconds) |
31 | `Retry-After` | Seconds until the window resets (only on 429 responses) |
32
38 -Treat these as the source of truth and drive your client off them.
33 +## Rate limit response
34
40 -### When you exceed the limit
41 -
42 -You get an `HTTP 429 Too Many Requests` with a `Retry-After` header:
35 +When you exceed the rate limit, you'll receive a `429 Too Many Requests` response:
36
37 ```json
38 {
@@ -47,53 +40,17 @@ You get an `HTTP 429 Too Many Requests` with a `Retry-After` header:
40 }
41 ```
42
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.
43 +## Best practices
44
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>
45 +1. **Monitor your usage** - Check the `X-RateLimit-Remaining` header to track how close you are to the limit.
46
90 -## High-volume and multi-tenant usage
47 +2. **Honor `Retry-After`** - On a `429`, wait for the duration in the `Retry-After` header before retrying.
48
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.
49 +3. **Cache responses** - Cache tool definitions and other static data to reduce unnecessary API calls.
50
51 ## Need higher limits?
52
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.
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.
54
55 <Cards>
56 <Card title="Errors" href="/reference/v3/errors">