Tool Failure
Tool failures occur when a tool cannot execute successfully. The agent must detect the failure, categorise it, and decide whether to retry, use a fallback, or escalate.
6 min•By Priygop Team•Updated 2026
Tool Failure Categories
- Transient failures: temporary issues that go away on their own — network glitches, short-lived service outages. Solution: retry after a short delay.
- Persistent failures: the service is fully down or unavailable for an extended period. Solution: use a fallback tool or escalate.
- Configuration failures: missing API keys, wrong endpoint URLs, invalid credentials. Solution: do not retry — fix the configuration and escalate.
- Capacity failures: the tool is overwhelmed — rate limits, service quotas. Solution: wait for the rate limit window to reset, then retry.
Tool Failure Handler
Tool Failure Handler
# Tool failure classification and response
def handle_tool_failure(error: dict, retry_count: int, max_retries: int = 3) -> dict:
"""
Classify a tool failure and decide the response strategy.
Returns an action: 'retry', 'fallback', 'escalate', or 'skip'.
"""
error_type = error.get("error_type", "unknown")
error_msg = error.get("error", "")
if error_type == "timeout":
if retry_count < max_retries:
wait = 2 ** retry_count # Exponential backoff: 1s, 2s, 4s
return {"action": "retry", "wait_seconds": wait,
"reason": f"Timeout — retrying in {wait}s"}
return {"action": "escalate", "reason": "Max retries exceeded on timeout"}
elif error_type == "rate_limit":
retry_after = error.get("retry_after_seconds", 60)
return {"action": "retry", "wait_seconds": retry_after,
"reason": f"Rate limited — waiting {retry_after}s"}
elif error_type == "network":
if retry_count < 2:
return {"action": "retry", "wait_seconds": 5,
"reason": "Network error — retrying"}
return {"action": "fallback", "reason": "Network error persists — trying fallback"}
elif error_type in ("auth", "permission"):
return {"action": "escalate",
"reason": f"Authentication/permission error — cannot retry: {error_msg}"}
elif error_type == "not_found":
return {"action": "skip", "reason": "Resource does not exist — skipping"}
elif error_type == "validation":
return {"action": "escalate",
"reason": f"Bad arguments sent to tool — cannot retry without fix: {error_msg}"}
return {"action": "escalate", "reason": f"Unknown error type '{error_type}'"}
# Test all failure types
for err in [
{"error_type": "timeout"},
{"error_type": "rate_limit", "retry_after_seconds": 30},
{"error_type": "auth", "error": "API key invalid"},
{"error_type": "not_found"},
]:
response = handle_tool_failure(err, retry_count=0)
print(f" {err['error_type']:12} → {response['action']}: {response['reason']}")Key Takeaways
- Tool failures occur when a tool cannot execute successfully.
- Transient failures: temporary issues that go away on their own — network glitches, short-lived service outages. Solution: retry after a short delay.
- Persistent failures: the service is fully down or unavailable for an extended period. Solution: use a fallback tool or escalate.
- Configuration failures: missing API keys, wrong endpoint URLs, invalid credentials. Solution: do not retry — fix the configuration and escalate.