Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
fix(core,python): correct rate-limit wording and cover the review gaps (PLEN-4561)
- waitForConnection's docs claimed a 429 wait stays within the timeout, but the client's own retries aren't bound by it: a 1s timeout with Retry-After: 3 takes 6s. Say so, and pin it with real-client tests in TS and Python. - Rate-limit errors now name the org, which is what the limit applies to, and only mention a wait the response gave. - Test the 500-entry limit, versions pinned through toolkitVersions, and a date-format Retry-After in TS. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
viraj committed
Nov 4, 2026 at 10:34 UTC
5ad765304d3a0bc50f789da8f4f3da3fc520c3ec
7 files changed
+151
-25
docs/content/docs/tools-direct/authenticating-tools.mdx
+1
-1
@@ -564,7 +564,7 @@ The method polls the Composio API, waiting 1 second between polls at first and u
564
- Enters a terminal state like **FAILED** or **EXPIRED** (throws an error)
565
- Exceeds the specified timeout (throws a timeout error)
566
567
-A rate-limited poll doesn't end the wait. The method waits as long as the response asks, within the timeout, and polls again.
567
+A rate-limited poll doesn't end the wait. The method waits as long as the response asks and polls again, and these retries can carry the wait past the timeout.
568
569
### Checking Connection Status
570
python/composio/core/models/connected_accounts.py
+5
-4
@@ -110,8 +110,9 @@ class ConnectionRequest(Resource):
110
111
The delay between polls grows from 1 second to 5 seconds, so a connection
112
can be up to 5 seconds old when this returns. A rate-limited poll doesn't
113
- fail the wait: it waits as long as the response asks, within the timeout,
114
- and polls again.
113
+ fail the wait: once the client's own retries run out, it waits as long as
114
+ the response asks, up to the timeout, and polls again. The client's retries
115
+ can carry the wait past the timeout, because they aren't bound by it.
116
117
:param timeout: The timeout to wait for the connection to be established.
118
:return: Connected account object.
@@ -144,8 +145,8 @@ class ConnectionRequest(Resource):
145
f"Timeout while waiting for connection {self.id} to be active"
146
),
147
)
147
- # Stop at the deadline rather than past it, so the last poll happens
148
- # as the time runs out.
148
+ # This delay stops at the deadline, so the last poll happens as the
149
+ # time runs out.
150
time.sleep(min(delay, remaining))
151
poll_delay = min(poll_delay * _POLL_DELAY_GROWTH, _MAX_POLL_DELAY_SECONDS)
152
python/tests/test_connected_accounts.py
+34
-2
@@ -6,9 +6,16 @@ from unittest.mock import Mock, patch
6
7
import httpx
8
import pytest
9
-from composio_client import BadRequestError, ConflictError, RateLimitError, omit
9
+from composio_client import (
10
+ BadRequestError,
11
+ ConflictError,
12
+ ProjectAuth,
13
+ RateLimitError,
14
+ omit,
15
+)
16
17
from composio import exceptions
18
+from composio.client import HttpClient
19
from composio.core.models.connected_accounts import (
20
AuthScheme,
21
ConnectedAccounts,
@@ -190,7 +197,32 @@ class TestConnectionRequestPolling:
197
assert self._request(client).wait_for_connection(timeout=60.0) is active
198
assert clock["now"] == 10.0
199
193
- def test_never_waits_past_the_timeout_for_a_429(self, monkeypatch):
200
+ def test_runs_past_the_timeout_while_the_real_client_retries_a_429(
201
+ self, monkeypatch
202
+ ):
203
+ clock = self._clock(monkeypatch)
204
+ requests = []
205
+
206
+ def handler(request):
207
+ requests.append(request)
208
+ return httpx.Response(
209
+ 429, headers={"retry-after": "3"}, json={"error": {"message": "x"}}
210
+ )
211
+
212
+ client = HttpClient(
213
+ provider="test",
214
+ auth=ProjectAuth("test-api-key"),
215
+ base_url="https://backend.invalid",
216
+ http_client=httpx.Client(transport=httpx.MockTransport(handler)),
217
+ )
218
+
219
+ with pytest.raises(exceptions.ComposioSDKTimeoutError):
220
+ self._request(client).wait_for_connection(timeout=1.0)
221
+
222
+ assert clock["now"] == 6.0
223
+ assert len(requests) == 3
224
+
225
+ def test_stops_its_own_delay_at_the_timeout_after_a_429(self, monkeypatch):
226
clock = self._clock(monkeypatch)
227
client = Mock()
228
client.connected_accounts.retrieve.side_effect = self._rate_limited("60")
ts/packages/core/src/errors/ToolErrors.ts
+13
-12
@@ -70,19 +70,20 @@ export class ComposioToolFetchError extends ComposioError {
70
}
71
}
72
73
-const RATE_LIMIT_FIXES = [
74
- 'Wait for the time given in retryAfterSeconds, then retry',
75
- 'Reduce how many requests this project sends per minute',
76
-];
77
-
73
/** Error options for a 429. Leaves out an unknown wait, as `ComposioError` does for unset fields. */
74
const rateLimitOptions = (cause: APIError, meta: Record<string, unknown>) => {
75
const retryAfterSeconds = getRetryAfterSeconds(cause);
76
return {
77
+ retryAfterSeconds,
78
cause,
79
statusCode: 429,
80
meta: retryAfterSeconds === undefined ? meta : { ...meta, retryAfterSeconds },
85
- possibleFixes: RATE_LIMIT_FIXES,
81
+ possibleFixes: [
82
+ retryAfterSeconds === undefined
83
+ ? 'Wait before retrying'
84
+ : `Wait ${Math.ceil(retryAfterSeconds)} seconds, then retry`,
85
+ 'Reduce how many requests your organization sends per minute',
86
+ ],
87
};
88
};
89
@@ -95,10 +96,10 @@ export class ComposioToolFetchRateLimitError extends ComposioToolFetchError {
96
declare public readonly retryAfterSeconds?: number;
97
98
constructor(message: string, cause: APIError, meta: Record<string, unknown> = {}) {
98
- const options = rateLimitOptions(cause, meta);
99
+ const { retryAfterSeconds, ...options } = rateLimitOptions(cause, meta);
100
super(message, options);
100
- if ('retryAfterSeconds' in options.meta) {
101
- this.retryAfterSeconds = getRetryAfterSeconds(cause);
101
+ if (retryAfterSeconds !== undefined) {
102
+ this.retryAfterSeconds = retryAfterSeconds;
103
}
104
this.name = 'ComposioToolFetchRateLimitError';
105
}
@@ -145,10 +146,10 @@ export class ComposioToolExecutionRateLimitError extends ComposioToolExecutionEr
146
declare public readonly retryAfterSeconds?: number;
147
148
constructor(message: string, cause: APIError, meta: Record<string, unknown> = {}) {
148
- const options = rateLimitOptions(cause, meta);
149
+ const { retryAfterSeconds, ...options } = rateLimitOptions(cause, meta);
150
super(message, options);
150
- if ('retryAfterSeconds' in options.meta) {
151
- this.retryAfterSeconds = getRetryAfterSeconds(cause);
151
+ if (retryAfterSeconds !== undefined) {
152
+ this.retryAfterSeconds = retryAfterSeconds;
153
}
154
this.name = 'ComposioToolExecutionRateLimitError';
155
}
ts/packages/core/src/models/ConnectionRequest.ts
+4
-3
@@ -63,8 +63,9 @@ export function createConnectionRequest(
63
* This method polls the Composio API to check the status of the connection request until it
64
* either becomes active, enters a terminal error state, or times out. The delay between polls
65
* grows from 1 second to 5 seconds, so a connection can be up to 5 seconds old when this returns.
66
- * A rate-limited poll doesn't fail the wait: it waits as long as the response asks, within the
67
- * timeout, and polls again.
66
+ * A rate-limited poll doesn't fail the wait: once the client's own retries run out, it waits as
67
+ * long as the response asks, up to the timeout, and polls again. The client's retries can carry
68
+ * the wait past the timeout, because they aren't bound by it.
69
*
70
* @param {number} [timeout=60000] - Maximum time to wait in milliseconds before timing out (default: 60 seconds)
71
* @returns {Promise<ConnectedAccountRetrieveResponse>} The final connected account response when successful
@@ -145,7 +146,7 @@ export function createConnectionRequest(
146
if (remaining <= 0) {
147
throw new ConnectionRequestTimeoutError(`Connection request timed out for ${request.id}`);
148
}
148
- // Stop at the deadline rather than past it, so the last poll happens as the time runs out.
149
+ // This delay stops at the deadline, so the last poll happens as the time runs out.
150
await new Promise(resolve => setTimeout(resolve, Math.min(delay, remaining)));
151
pollDelay = Math.min(pollDelay * POLL_DELAY_GROWTH, MAX_POLL_DELAY_MS);
152
}
ts/packages/core/test/connectedAccounts/connectionRequest.test.ts
+58
-2
@@ -1,7 +1,13 @@
1
import { describe, it, expect, vi, beforeEach } from 'vitest';
2
import { createConnectionRequest } from '../../src/models/ConnectionRequest';
3
import { ConnectionRequest } from '../../src/types/connectionRequest.types';
4
-import ComposioClient, { APIError, ComposioError, RateLimitError } from '@composio/client';
4
+import ComposioClient, {
5
+ APIError,
6
+ Auth,
7
+ ComposioError,
8
+ createFetchTransport,
9
+ RateLimitError,
10
+} from '@composio/client';
11
import {
12
ComposioConnectedAccountNotFoundError,
13
ConnectionRequestFailedError,
@@ -376,7 +382,7 @@ describe('ConnectionRequest', () => {
382
expect(await result).toHaveProperty('status', ConnectedAccountStatuses.ACTIVE);
383
});
384
379
- it('never waits past the timeout for a 429', async () => {
385
+ it('stops its own delay at the timeout after a 429', async () => {
386
mockClient.connectedAccounts.retrieve.mockRejectedValue(rateLimited({ 'retry-after': '60' }));
387
388
const result = start(5000);
@@ -386,6 +392,56 @@ describe('ConnectionRequest', () => {
392
expect(mockClient.connectedAccounts.retrieve).toHaveBeenCalledTimes(2);
393
});
394
395
+ it('reads a date-format Retry-After', async () => {
396
+ vi.useFakeTimers({ now: Date.UTC(2026, 0, 1) });
397
+ mockClient.connectedAccounts.retrieve
398
+ .mockRejectedValueOnce(rateLimited({ 'retry-after': 'Thu, 01 Jan 2026 00:00:10 GMT' }))
399
+ .mockRejectedValue(new APIError(500, undefined, 'stop', new Headers()));
400
+
401
+ const result = createConnectionRequest(
402
+ mockClient as unknown as ComposioClient,
403
+ connectedAccountId
404
+ )
405
+ .waitForConnection()
406
+ .catch(error => error);
407
+ await vi.advanceTimersByTimeAsync(9999);
408
+ expect(mockClient.connectedAccounts.retrieve).toHaveBeenCalledTimes(1);
409
+
410
+ await vi.advanceTimersByTimeAsync(1);
411
+ expect(mockClient.connectedAccounts.retrieve).toHaveBeenCalledTimes(2);
412
+ await result;
413
+ });
414
+
415
+ it('runs past the timeout while the real client retries a 429', async () => {
416
+ vi.useFakeTimers();
417
+ const fetch = vi.fn<typeof globalThis.fetch>(
418
+ async () =>
419
+ new Response(JSON.stringify({ error: { message: 'slow down' } }), {
420
+ status: 429,
421
+ headers: { 'content-type': 'application/json', 'retry-after': '3' },
422
+ })
423
+ );
424
+ const client = new ComposioClient({
425
+ auth: Auth.project('test-api-key'),
426
+ baseURL: 'https://backend.invalid',
427
+ transport: createFetchTransport({ fetch }),
428
+ });
429
+ let settled = false;
430
+ const result = createConnectionRequest(client, connectedAccountId)
431
+ .waitForConnection(1000)
432
+ .catch(error => error)
433
+ .finally(() => {
434
+ settled = true;
435
+ });
436
+
437
+ await vi.advanceTimersByTimeAsync(5999);
438
+ expect(settled).toBe(false);
439
+
440
+ await vi.advanceTimersByTimeAsync(1);
441
+ expect(await result).toBeInstanceOf(ConnectionRequestTimeoutError);
442
+ expect(fetch).toHaveBeenCalledTimes(3);
443
+ });
444
+
445
it('keeps its usual delay when a 429 has no usable Retry-After', async () => {
446
mockClient.connectedAccounts.retrieve.mockRejectedValue(
447
rateLimited({ 'retry-after': 'soon' })
ts/packages/core/test/tools/executeSchemaCache.test.ts
+36
-1
@@ -113,6 +113,37 @@ describe('tools.execute schema cache', () => {
113
expect(retrieve).toHaveBeenCalledTimes(2);
114
});
115
116
+ it('uses the pinned lifetime for a version set in toolkitVersions', async () => {
117
+ vi.useFakeTimers({ toFake: ['Date'] });
118
+ const { tools, retrieve } = createTools({
119
+ toolkitVersions: { [toolMocks.rawTool.toolkit.slug]: '20250909_00' },
120
+ });
121
+
122
+ await run(tools);
123
+ vi.advanceTimersByTime(60 * 60 * 1000 - 1);
124
+ await run(tools);
125
+ expect(retrieve).toHaveBeenCalledTimes(1);
126
+
127
+ vi.advanceTimersByTime(1);
128
+ await run(tools);
129
+ expect(retrieve).toHaveBeenCalledTimes(2);
130
+ });
131
+
132
+ it('drops the oldest schema past 500 entries', async () => {
133
+ const { tools, retrieve } = createTools();
134
+
135
+ for (let i = 0; i <= 500; i++) {
136
+ await run(tools, `v${i}`);
137
+ }
138
+ expect(retrieve).toHaveBeenCalledTimes(501);
139
+
140
+ // The newest entry is still cached, and the oldest was dropped.
141
+ await run(tools, 'v500');
142
+ expect(retrieve).toHaveBeenCalledTimes(501);
143
+ await run(tools, 'v0');
144
+ expect(retrieve).toHaveBeenCalledTimes(502);
145
+ });
146
+
147
it('does not cache a failed fetch', async () => {
148
const retrieve = vi
149
.fn<() => Response>()
@@ -162,7 +193,10 @@ describe('rate limit errors', () => {
193
expect(isComposioRateLimitError(error)).toBe(true);
194
expect(error.retryAfterSeconds).toBe(7);
195
expect(error.statusCode).toBe(429);
165
- expect(error.possibleFixes.join(' ')).not.toContain('slug');
196
+ expect(error.possibleFixes).toEqual([
197
+ 'Wait 7 seconds, then retry',
198
+ 'Reduce how many requests your organization sends per minute',
199
+ ]);
200
expect(execute).not.toHaveBeenCalled();
201
});
202
@@ -188,6 +222,7 @@ describe('rate limit errors', () => {
222
223
expect(isComposioRateLimitError(error)).toBe(true);
224
expect(Object.keys(error)).not.toContain('retryAfterSeconds');
225
+ expect(error.possibleFixes[0]).toBe('Wait before retrying');
226
});
227
228
it('does not report other failures as rate limits', async () => {