Beginner-Friendly Topic

Take your time - it's perfectly normal to re-read this topic 2-3 times. Try the interactive code editor below to run code yourself. Use the Q&A section to check your understanding before moving on.You've got this!

Tool Errors

Tool errors happen. APIs timeout. Databases go offline. Functions receive unexpected data. Good agents handle these errors gracefully rather than crashing.

8 min•By Priygop Team•Updated 2026

Common Tool Error Types

Validation error: the arguments provided by the agent are invalid
Network error: the external API or service could not be reached
Authentication error: the tool's credentials are missing or expired
Not found error: the resource requested does not exist
Rate limit error: too many requests in a short time
Timeout error: the tool took too long to respond
Permission error: the agent does not have access to this resource

Error Handling Pattern

# A robust tool with comprehensive error handling
import time
import requests

def get_weather(city: str, retry_count: int = 0) -> dict:
    """Get current weather for a city. Retries once on network errors."""

    if not city or not city.strip():
        return {
            "status": "error",
            "error_type": "validation",
            "error": "City name cannot be empty"
        }

    try:
        # Simulated API call
        # response = requests.get(f"https://api.weather.com/v1/{city}", timeout=10)
        # In a real tool, handle the real HTTP response

        # Simulated success
        return {
            "status": "success",
            "city": city,
            "temperature_c": 22,
            "condition": "Partly cloudy",
            "humidity_pct": 65
        }

    except requests.Timeout:
        if retry_count < 1:
            time.sleep(2)
            return get_weather(city, retry_count + 1)
        return {"status": "error", "error_type": "timeout",
                "error": "Weather API timed out after retry"}

    except requests.ConnectionError:
        return {"status": "error", "error_type": "network",
                "error": "Could not connect to weather service"}

    except Exception as e:
        return {"status": "error", "error_type": "unknown", "error": str(e)}

result = get_weather("London")
print(result)

Key Takeaways

Tool errors happen.
Validation error: the arguments provided by the agent are invalid
Network error: the external API or service could not be reached
Authentication error: the tool's credentials are missing or expired

Topics in This Module

Common Tool Error Types

Validation error: the arguments provided by the agent are invalid

Network error: the external API or service could not be reached

Authentication error: the tool's credentials are missing or expired

Not found error: the resource requested does not exist

Rate limit error: too many requests in a short time

Timeout error: the tool took too long to respond

Permission error: the agent does not have access to this resource

Error Handling Pattern

# A robust tool with comprehensive error handling
import time
import requests

def get_weather(city: str, retry_count: int = 0) -> dict:
    """Get current weather for a city. Retries once on network errors."""

    if not city or not city.strip():
        return {
            "status": "error",
            "error_type": "validation",
            "error": "City name cannot be empty"
        }

    try:
        # Simulated API call
        # response = requests.get(f"https://api.weather.com/v1/{city}", timeout=10)
        # In a real tool, handle the real HTTP response

        # Simulated success
        return {
            "status": "success",
            "city": city,
            "temperature_c": 22,
            "condition": "Partly cloudy",
            "humidity_pct": 65
        }

    except requests.Timeout:
        if retry_count < 1:
            time.sleep(2)
            return get_weather(city, retry_count + 1)
        return {"status": "error", "error_type": "timeout",
                "error": "Weather API timed out after retry"}

    except requests.ConnectionError:
        return {"status": "error", "error_type": "network",
                "error": "Could not connect to weather service"}

    except Exception as e:
        return {"status": "error", "error_type": "unknown", "error": str(e)}

result = get_weather("London")
print(result)

Topics in This Module