fix(core): raise tool not found only on 404/400 (#4459)

This PR:

- closes [PRDE-1613](https://linear.app/composio/issue/PRDE-1613)
- maps only 404/400 from `tools.retrieve` to
`ComposioToolNotFoundError`; every other failure (401 invalid API key,
5xx, network) now raises the new `ComposioToolFetchError` with the
client error kept as `cause`
- `tools.get(userId, slug)` and `tools.execute` inherit the corrected
mapping since they call `getRawComposioToolBySlug`
- fixes `toolkits.get(slug)`, whose 404/400 check compared against the
OpenAI `APIError` class instead of the Composio client one, so
`ComposioToolkitNotFoundError` never fired
- Python parity: `get_raw_composio_tool_by_slug` raises
`ToolNotFoundError` (now a `NotFoundError` subclass) on 404/400 and
re-raises any other `composio_client` error unchanged
- adds unit tests on both sides for 404, 400, 401 and non-API failures;
verified live against the API with an invalid key on both SDKs

## Context

An unauthenticated call to `tools.getRawComposioToolBySlug` returned
`error.name === "ComposioToolNotFoundError"` while `error.cause.status`
was 401. The catch block wrapped every error except cancellation as
not-found, which predates the `@composio/client@beta` swap. Intended to
be back-ported to `main` after merging to `next`.

https://claude.ai/code/session_017HtbhwMAKcfebo8HyXWa5s

Author: jkomyno

.changeset/tool-not-found-only-on-404.md

@@ -0,0 +1,5 @@
+---
+'@composio/core': patch
+---
+
+Stop reporting every failed tool lookup as `ComposioToolNotFoundError`. `tools.getRawComposioToolBySlug`, and the `tools.get` / `tools.execute` paths that call it, now raise `ComposioToolNotFoundError` only when the API answers 404 or 400. Any other failure, such as an invalid API key (401), a server error, or a network fault, raises the new `ComposioToolFetchError` with the client error preserved as `cause`. `toolkits.get(slug)` now applies its 404/400 check against the Composio client's `APIError` instead of the OpenAI one, so an unknown toolkit raises `ComposioToolkitNotFoundError` as documented.

python/composio/core/models/tools.py

@@ -6,7 +6,7 @@
 from pathlib import Path
 
 import typing_extensions as te
-from composio_client import omit
+from composio_client import APIStatusError, omit
 from pydantic import BaseModel as PydanticBaseModel
 
 from composio.client import HttpClient
@@ -28,7 +28,11 @@
 from composio.core.provider.base import BaseProvider, ExecuteToolFn
 from composio.core.provider.none_agentic import NonAgenticProvider
 from composio.core.types import ToolkitVersionParam
-from composio.exceptions import InvalidParams, ToolVersionRequiredError
+from composio.exceptions import (
+    InvalidParams,
+    ToolNotFoundError,
+    ToolVersionRequiredError,
+)
 from composio.utils.pydantic import none_to_omit
 from composio.utils.toolkit_version import get_toolkit_version
 from composio.utils.upload_dir_allowlist import resolve_effective_upload_allowlist
@@ -199,13 +203,21 @@ def __init__(
     def get_raw_composio_tool_by_slug(self, slug: str) -> Tool:
         """
         Returns schema for the given tool slug.
+
+        :raises ToolNotFoundError: when the backend reports the slug as unknown
+            (404, or 400 for a malformed slug). Any other client error, such as
+            an invalid API key, is re-raised unchanged.
         """
-        return _normalize_tool(
-            self._client.tools.retrieve(
+        try:
+            response = self._client.tools.retrieve(
                 tool_slug=slug,
                 toolkit_versions=none_to_omit(self._toolkit_versions),
-            ),
-        )
+            )
+        except APIStatusError as error:
+            if error.status_code in (400, 404):
+                raise ToolNotFoundError(f"Tool with slug {slug} not found") from error
+            raise
+        return _normalize_tool(response)
 
     def get_raw_composio_tools(
         self,

python/composio/exceptions.py

@@ -449,8 +449,13 @@ class InvalidExecuteFunctionError(ComposioError):
     pass
 
 
-class ToolNotFoundError(ComposioError):
-    pass
+class ToolNotFoundError(NotFoundError):
+    """Raised when a tool slug does not exist.
+
+    Mirrors the TypeScript SDK's ``ComposioToolNotFoundError``. Other failures
+    while fetching a tool (invalid API key, server or network errors) are not
+    translated and surface as the underlying ``composio_client`` error.
+    """
 
 
 class InvalidModifier(ComposioError):

python/tests/test_tool_retrieval_errors.py

@@ -0,0 +1,73 @@
+"""Error mapping for ``Tools.get_raw_composio_tool_by_slug``.
+
+Only an unknown slug becomes ``ToolNotFoundError``. Other client failures,
+such as an invalid API key, must surface unchanged so callers can tell a
+missing tool from a rejected request (parity with the TypeScript SDK).
+"""
+
+from unittest.mock import Mock
+
+import httpx
+import pytest
+from composio_client import AuthenticationError, BadRequestError, NotFoundError
+
+from composio import exceptions
+from composio.core.models.tools import Tools
+from tests.conftest import mock_http_client
+
+
+def _status_error(cls, status: int):
+    request = httpx.Request("GET", "https://backend.composio.dev/api/v3/tools/X")
+    response = httpx.Response(status, request=request)
+    return cls("error", response=response, body=None)
+
+
+@pytest.fixture
+def mock_client() -> Mock:
+    return mock_http_client()
+
+
+@pytest.fixture
+def tools(mock_client: Mock) -> Tools:
+    return Tools(client=mock_client, provider=Mock())
+
+
+def test_unknown_slug_raises_tool_not_found(tools: Tools, mock_client: Mock) -> None:
+    not_found = _status_error(NotFoundError, 404)
+    mock_client.tools.retrieve.side_effect = not_found
+
+    with pytest.raises(exceptions.ToolNotFoundError) as exc_info:
+        tools.get_raw_composio_tool_by_slug("NONEXISTENT_TOOL")
+
+    assert exc_info.value.__cause__ is not_found
+    assert isinstance(exc_info.value, exceptions.NotFoundError)
+    assert "NONEXISTENT_TOOL" in str(exc_info.value)
+
+
+def test_malformed_slug_raises_tool_not_found(tools: Tools, mock_client: Mock) -> None:
+    mock_client.tools.retrieve.side_effect = _status_error(BadRequestError, 400)
+
+    with pytest.raises(exceptions.ToolNotFoundError):
+        tools.get_raw_composio_tool_by_slug("malformed slug")
+
+
+def test_invalid_api_key_is_not_tool_not_found(tools: Tools, mock_client: Mock) -> None:
+    unauthorized = _status_error(AuthenticationError, 401)
+    mock_client.tools.retrieve.side_effect = unauthorized
+
+    with pytest.raises(AuthenticationError) as exc_info:
+        tools.get_raw_composio_tool_by_slug("SLACK_FETCH_CONVERSATION_HISTORY")
+
+    assert exc_info.value is unauthorized
+    assert exc_info.value.status_code == 401
+
+
+def test_execute_surfaces_auth_error_from_schema_fetch(
+    tools: Tools, mock_client: Mock
+) -> None:
+    mock_client.tools.retrieve.side_effect = _status_error(AuthenticationError, 401)
+
+    with pytest.raises(AuthenticationError):
+        tools.execute("SLACK_FETCH_CONVERSATION_HISTORY", {}, user_id="user")
+
+    mock_client.tools.execute.assert_not_called()

ts/packages/core/src/errors/ToolErrors.ts

@@ -5,6 +5,7 @@ import { ComposioConnectedAccountNotFoundError } from './ConnectedAccountsErrors
 export const ToolErrorCodes = {
   TOOLSET_NOT_DEFINED: 'TOOLSET_NOT_DEFINED',
   TOOL_NOT_FOUND: 'TOOL_NOT_FOUND',
+  TOOL_FETCH_ERROR: 'TOOL_FETCH_ERROR',
   INVALID_MODIFIER: 'INVALID_MODIFIER',
   TOOL_EXECUTION_ERROR: 'TOOL_EXECUTION_ERROR',
   INVALID_TOOL_ARGUMENTS: 'INVALID_TOOL_ARGUMENTS',
@@ -45,6 +46,29 @@ export class ComposioToolNotFoundError extends ComposioError {
   }
 }
 
+/**
+ * Error thrown when a tool schema could not be fetched for a reason other than
+ * the tool not existing (for example an invalid API key, a server error, or a
+ * network failure). The underlying client error is preserved as `cause`.
+ */
+export class ComposioToolFetchError extends ComposioError {
+  constructor(
+    message: string = 'Failed to fetch tool',
+    options: Omit<ComposioErrorOptions, 'code' | 'statusCode'> = {}
+  ) {
+    super(message, {
+      ...options,
+      code: ToolErrorCodes.TOOL_FETCH_ERROR,
+      possibleFixes: options.possibleFixes || [
+        'Ensure the tool slug is valid',
+        'Ensure you are using the correct API key',
+        'Ensure you are using the correct API endpoint / Base URL and it is working',
+      ],
+    });
+    this.name = 'ComposioToolFetchError';
+  }
+}
+
 export class ComposioInvalidModifierError extends ComposioError {
   constructor(
     message: string = 'Invalid modifier',

ts/packages/core/src/models/Toolkits.ts

@@ -1,4 +1,4 @@
-import ComposioClient from '@composio/client';
+import ComposioClient, { APIError } from '@composio/client';
 import {
   ToolkitListParams,
   ToolKitListResponse,
@@ -16,7 +16,6 @@ import { ConnectionRequest } from '../types/connectionRequest.types';
 import { telemetry } from '../telemetry/Telemetry';
 import { AuthSchemeType } from '../types/authConfigs.types';
 import logger from '../utils/logger';
-import { APIError } from 'openai';
 import {
   transformToolkitListResponse,
   transformToolkitRetrieveCategoriesResponse,

ts/packages/core/src/models/Tools.ts

@@ -1,4 +1,4 @@
-import ComposioClient from '@composio/client';
+import ComposioClient, { APIError } from '@composio/client';
 import { FileToolModifier } from '#file_tool_modifier';
 import {
   Tool,
@@ -42,6 +42,7 @@ import logger from '../utils/logger';
 import { ExecuteToolFn, GlobalExecuteToolFn } from '../types/provider.types';
 import {
   ComposioInvalidModifierError,
+  ComposioToolFetchError,
   ComposioToolNotFoundError,
   ComposioProviderNotDefinedError,
   ComposioToolVersionRequiredError,
@@ -710,7 +711,17 @@ export class Tools<
       if (error instanceof ComposioRequestCancelledError) {
         throw error;
       }
-      throw new ComposioToolNotFoundError(`Unable to retrieve tool with slug ${slug}`, {
+      // The tools endpoint reports an unknown slug as 404 (or 400 for a
+      // malformed one). Anything else (401, 5xx, network) is not "not found",
+      // so keep the client error reachable as `cause` under a generic error.
+      if (error instanceof APIError && (error.status === 404 || error.status === 400)) {
+        throw new ComposioToolNotFoundError(`Tool with slug ${slug} not found`, {
+          meta: { slug },
+          cause: error,
+        });
+      }
+      throw new ComposioToolFetchError(`Unable to retrieve tool with slug ${slug}`, {
+        meta: { slug },
         cause: error,
       });
     }

ts/packages/core/test/models/toolkits.test.ts

@@ -3,6 +3,10 @@ import { Toolkits } from '../../src/models/Toolkits';
 import ComposioClient from '@composio/client';
 import { telemetry } from '../../src/telemetry/Telemetry';
 import { ComposioAuthConfigNotFoundError } from '../../src/errors/AuthConfigErrors';
+import {
+  ComposioToolkitFetchError,
+  ComposioToolkitNotFoundError,
+} from '../../src/errors/ToolkitErrors';
 import { AuthSchemeTypes } from '../../src/types/authConfigs.types';
 import { APIError } from '@composio/client';
 import type { ToolkitListParams } from '../../src/types/toolkit.types';
@@ -233,10 +237,33 @@ describe('Toolkits', () => {
       await expect(promise).rejects.toThrowError('Failed to fetch toolkits');
     });
 
-    it('should throw ComposioToolkitNotFoundError when toolkit not found', async () => {
-      mockClient.toolkits.retrieve.mockRejectedValue(
-        new Error('Toolkit with slug non-existent not found')
+    it('should throw ComposioToolkitNotFoundError when the API returns 404', async () => {
+      const notFound = new ComposioClient.NotFoundError(404, undefined, undefined, new Headers());
+      mockClient.toolkits.retrieve.mockRejectedValueOnce(notFound);
+
+      const error = await toolkits.get('non-existent').catch(e => e);
+
+      expect(error).toBeInstanceOf(ComposioToolkitNotFoundError);
+      expect(error.cause).toBe(notFound);
+    });
+
+    it('should not report an invalid API key (401) as toolkit not found', async () => {
+      const unauthorized = new ComposioClient.AuthenticationError(
+        401,
+        undefined,
+        undefined,
+        new Headers()
       );
+      mockClient.toolkits.retrieve.mockRejectedValueOnce(unauthorized);
+
+      const error = await toolkits.get('github').catch(e => e);
+
+      expect(error).toBeInstanceOf(ComposioToolkitFetchError);
+      expect(error.cause).toBe(unauthorized);
+    });
+
+    it('should throw ComposioToolkitFetchError for non-API failures', async () => {
+      mockClient.toolkits.retrieve.mockRejectedValueOnce(new Error('socket hang up'));
 
       const promise = toolkits.get('non-existent');
       await expect(promise).rejects.toThrowError("Couldn't fetch Toolkit with slug: non-existent");
@@ -530,7 +557,8 @@ describe('Toolkits', () => {
 
       const promise = toolkits.authorize('user-123', 'non-existent');
 
-      await expect(promise).rejects.toThrow("Couldn't fetch Toolkit with slug: non-existent");
+      await expect(promise).rejects.toThrow(ComposioToolkitNotFoundError);
+      await expect(promise).rejects.toThrow('Toolkit with slug non-existent not found');
       expect(mockClient.authConfigs.list).not.toHaveBeenCalled();
       expect(mockClient.authConfigs.create).not.toHaveBeenCalled();
       expect(mockClient.connectedAccounts.create).not.toHaveBeenCalled();

ts/packages/core/test/tools/tools.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import ComposioClient from '@composio/client';
 import { mockClient } from '../utils/mocks/client.mock';
 import { toolMocks } from '../utils/mocks/data.mock';
 import { Tool, ToolListParams, ToolExecuteParams } from '../../src/types/tool.types';
@@ -12,6 +13,7 @@ import {
 } from '../utils/toolExecuteUtils';
 import { MockProvider } from '../utils/mocks/provider.mock';
 import { ValidationError } from '../../src/errors/ValidationErrors';
+import { ComposioToolFetchError, ComposioToolNotFoundError } from '../../src/errors/ToolErrors';
 
 // Minimal structural shape for a ComposioError-like value (possibly wrapping
 // another error as its `cause`), used to narrow `catch (error: unknown)`
@@ -455,14 +457,67 @@ describe('Tools', () => {
       expect(result.slug).toEqual(toolMocks.transformedTool.slug);
     });
 
-    it('should throw an error if tool is not found', async () => {
+    it('should throw ComposioToolNotFoundError when the API returns 404', async () => {
       const slug = 'NONEXISTENT_TOOL';
+      const notFound = new ComposioClient.NotFoundError(404, undefined, undefined, new Headers());
 
-      mockClient.tools.retrieve.mockRejectedValue(null);
+      mockClient.tools.retrieve.mockRejectedValueOnce(notFound);
 
-      await expect(context.tools.getRawComposioToolBySlug(slug)).rejects.toThrow(
-        `Unable to retrieve tool with slug ${slug}`
+      const error = await context.tools.getRawComposioToolBySlug(slug).catch(e => e);
+
+      expect(error).toBeInstanceOf(ComposioToolNotFoundError);
+      expect(error.message).toBe(`Tool with slug ${slug} not found`);
+      expect(error.cause).toBe(notFound);
+    });
+
+    it('should throw ComposioToolNotFoundError when the API returns 400', async () => {
+      const slug = 'malformed slug';
+      const badRequest = new ComposioClient.BadRequestError(
+        400,
+        undefined,
+        undefined,
+        new Headers()
+      );
+
+      mockClient.tools.retrieve.mockRejectedValueOnce(badRequest);
+
+      const error = await context.tools.getRawComposioToolBySlug(slug).catch(e => e);
+
+      expect(error).toBeInstanceOf(ComposioToolNotFoundError);
+      expect(error.cause).toBe(badRequest);
+    });
+
+    it('should not report an invalid API key (401) as tool not found', async () => {
+      const slug = 'SLACK_FETCH_CONVERSATION_HISTORY';
+      const unauthorized = new ComposioClient.AuthenticationError(
+        401,
+        { error: { message: 'Invalid API key', code: 801, status: 401 } },
+        undefined,
+        new Headers()
       );
+
+      mockClient.tools.retrieve.mockRejectedValueOnce(unauthorized);
+
+      const error = await context.tools.getRawComposioToolBySlug(slug).catch(e => e);
+
+      expect(error).toBeInstanceOf(ComposioToolFetchError);
+      expect(error).not.toBeInstanceOf(ComposioToolNotFoundError);
+      expect(error.name).toBe('ComposioToolFetchError');
+      expect(error.message).toBe(`Unable to retrieve tool with slug ${slug}`);
+      expect(error.cause).toBe(unauthorized);
+      expect(error.cause.status).toBe(401);
+    });
+
+    it('should wrap non-API failures in ComposioToolFetchError', async () => {
+      const slug = 'TOOL_SLUG';
+      const networkError = new Error('socket hang up');
+
+      mockClient.tools.retrieve.mockRejectedValueOnce(networkError);
+
+      const error = await context.tools.getRawComposioToolBySlug(slug).catch(e => e);
+
+      expect(error).toBeInstanceOf(ComposioToolFetchError);
+      expect(error.cause).toBe(networkError);
     });
 
     it('should apply schema modifiers when provided', async () => {