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

feat(core,python): handle rate limits in tool execution and connection polling (PLEN-4561) (#5210)

## Why Apollo is starting to enforce per-org rate-limit buckets. Two SDK patterns spend that quota for little value: - TS `tools.execute()` fetches the tool schema on every call, so each execution also spends a `discovery` request. If that fetch gets a 429, the tool never runs, and the error suggests checking the slug or API key. - `waitForConnection` polls every second, about 61 requests in the default 60s wait, and a 429 ends the wait. Ticket: [PLEN-4561](https://linear.app/composio/issue/PLEN-4561). This PR is the core SDK part. The `composio-client` `Retry-After` fix, the CLI changes and the rate-limit docs follow separately. ## What - **Schema reuse (TS):** `tools.execute()` reuses a fetched schema for 5 minutes on `latest` and 1 hour on a pinned version, keyed by slug and version. It keeps at most 500 per `Tools` instance and doesn't cache failures. `getRawComposioToolBySlug` stays uncached, and caller schema modifiers never reach the cache. - **Rate-limit errors (TS):** a 429 throws `ComposioToolFetchRateLimitError` or `ComposioToolExecutionRateLimitError`, with `retryAfterSeconds` and fixes that no longer blame the slug. They subclass the existing errors and keep their codes, so existing handlers still work. `isComposioRateLimitError` catches both. - **Polling (TS, Python):** the delay grows from 1s to a 5s cap, which is 16 requests in a 60s wait with no 429s. A 429 no longer ends the wait: once the client's own retries run out, it waits as long as the response asks, up to the timeout, then polls again. The last poll lands on the deadline. Python already caches schemas and already surfaces `composio_client.RateLimitError`, so only its polling changes. ## Impact - A completed connection can take up to 5s to be noticed, instead of 1s. - A `latest` schema can be up to 5 minutes stale in `tools.execute()`. The schema is used there for the toolkit slug and file handling. - TS: a connection deleted mid-wait now throws `ComposioConnectedAccountNotFoundError`, as the method already documented, instead of the raw client error. - Python: `wait_for_connection(timeout=0)` now polls once instead of timing out immediately. ## Review guidelines - **The timeout isn't a hard limit under 429s.** The client retries inside each poll and isn't bound by the timeout, as it wasn't before this PR: a 1s timeout with `Retry-After: 3` takes 6s and 3 requests. Tests pin this in both SDKs. `maxRetries: 0` on polls would enforce the timeout, but the loop would then have to handle 5xx and network errors itself, so I left it out. - **Concurrent first calls aren't deduplicated.** Several calls for the same uncached tool each fetch the schema. Sharing one fetch would let one caller's abort signal fail another's call. - **Error API.** Two classes plus a helper keep `instanceof` working for each existing error. Their constructor is `(message, cause, meta)` rather than the usual `(message, options)`, because a 429 is always built from the client error. Happy to change either. ## Not covered - Tool Router sessions aren't changed: `isComposioRateLimitError` doesn't catch 429s from `executeSessionTool`, `session.execute()` or `session.proxyExecute()`, which still surface the client error. - The Python schema cache still never expires and ignores the version. That's existing behavior and doesn't add requests. - The SDK reference page regenerates from the updated docstring, so it isn't edited here. ## Testing - CI runs the TS suites, the Python suite on 3.11, 3.13 and 3.15, and the E2E runs. - The docs preview on Vercel didn't build because of a two-factor authentication error on the team, so the `authenticating-tools.mdx` change hasn't been previewed. - Not exercised on the local stack or against a real Apollo 429. Tests run real clients against mocked HTTP responses for tool calls and for the timeout behavior, and mocked client calls for the polling schedule. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Viraj committed Nov 5, 2026 at 09:59 UTC 29698b7e54ff5d2c003d2b2e42c258fb7a0b5dc3

No changes.