{"record":{"id":"b583faaa069be21d","repo":"crewAIInc/crewAI","slug":"api-error-error-msg","errorCode":null,"errorMessage":"API Error: {error_msg}","messagePattern":"API Error: (.+?)","errorType":"exception","errorClass":"MergeAgentHandlerToolError","httpStatus":null,"severity":"error","filePath":"lib/crewai-tools/src/crewai_tools/tools/merge_agent_handler_tool/merge_agent_handler_tool.py","lineNumber":107,"sourceCode":"        }\n\n        if params:\n            payload[\"params\"] = params\n\n        logger.debug(f\"MCP Request to {url}: {json.dumps(payload, indent=2)}\")\n\n        try:\n            response = requests.post(url, json=payload, headers=headers, timeout=60)\n            response.raise_for_status()\n            result = response.json()\n\n            if \"error\" in result:\n                error_msg = result[\"error\"].get(\"message\", \"Unknown error\")\n                error_code = result[\"error\"].get(\"code\", -1)\n                logger.error(\n                    f\"Agent Handler API error (code {error_code}): {error_msg}\"\n                )\n                raise MergeAgentHandlerToolError(f\"API Error: {error_msg}\")\n\n            return cast(dict[str, Any], result)\n\n        except requests.exceptions.RequestException as e:\n            logger.error(f\"Failed to call Agent Handler API: {e!s}\")\n            raise MergeAgentHandlerToolError(\n                f\"Failed to communicate with Agent Handler API: {e!s}\"\n            ) from e\n\n    def _run(self, **kwargs: Any) -> Any:\n        \"\"\"Execute the Agent Handler tool with the given arguments.\"\"\"\n        try:\n            logger.info(f\"Executing {self.tool_name} with arguments: {kwargs}\")\n\n            result = self._make_mcp_request(\n                method=\"tools/call\",\n                params={\"name\": self.tool_name, \"arguments\": kwargs},\n            )","sourceCodeStart":89,"sourceCodeEnd":125,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/crewai-tools/src/crewai_tools/tools/merge_agent_handler_tool/merge_agent_handler_tool.py#L89-L125","documentation":"The Merge Agent Handler endpoint speaks JSON-RPC 2.0 over HTTP; when a 2xx response body contains an \"error\" object, _make_mcp_request extracts error.message (and logs the code) and re-raises it wrapped in MergeAgentHandlerToolError as \"API Error: ...\". This means transport succeeded but the server rejected the call — bad method, invalid params, unknown tool name, or auth/permission issues at the RPC layer.","triggerScenarios":"Calling _run with a tool_name not present in the tool pack (tools/call with unknown name); malformed MCP params; wrong tool_pack_id or registered_user_id in the URL; expired/invalid AGENT_HANDLER_API_KEY causing an RPC-level error object.","commonSituations":"Typos in tool_name; tool pack re-published under a new id; a registered user token revoked; passing arguments that fail the remote tool's schema validation.","solutions":["List valid tools first via MergeAgentHandlerTool.from_tool_name / a tools/list call and use an exact tool name","Verify tool_pack_id and registered_user_id match the Merge dashboard values","Check the logged error code (logger.error prints it) and rotate AGENT_HANDLER_API_KEY if it indicates auth failure","Print the kwargs you send and compare against the tool's inputSchema from tools/list"],"exampleFix":"# before\ntool = MergeAgentHandlerTool.from_tool_name(\n    tool_name=\"list_invoices\",  # wrong name\n    tool_pack_id=PACK_ID, registered_user_id=UID,\n)\n\n# after\n# discover exact names first\n# tools/list -> [{\"name\": \"invoices-list\", \"inputSchema\": {...}}, ...]\ntool = MergeAgentHandlerTool.from_tool_name(\n    tool_name=\"invoices-list\",\n    tool_pack_id=PACK_ID, registered_user_id=UID,\n)","handlingStrategy":"try-catch","validationCode":"# Verify the tool name exists before calling it\nnames = {t[\"name\"] for t in discover_tool_pack(PACK_ID, UID)}\nassert desired_tool_name in names, f\"unknown tool; available: {sorted(names)}\"","typeGuard":null,"tryCatchPattern":"from crewai_tools.tools.merge_agent_handler_tool.merge_agent_handler_tool import MergeAgentHandlerToolError\n\ntry:\n    result = tool._run(**kwargs)\nexcept MergeAgentHandlerToolError as e:\n    if str(e).startswith(\"API Error:\"):\n        # server rejected the RPC call: log and surface, do not retry blindly\n        logging.error(\"Agent Handler rejected call: %s\", e)\n        raise\n    raise","preventionTips":["Discover tool names via tools/list once and cache them","Validate kwargs against the tool's inputSchema before calling","Distinguish RPC errors (no retry) from transport errors (retryable)"],"tags":["api","json-rpc","merge","remote-error","crewai-tools"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}