Tool errors: distinguish retryable and permanent failures

Retrying every exception wastes time and can repeat writes. Error contracts should distinguish transient availability from invalid requests, denied authority and business rejection.

Route stable reason codes

The agent controls lab defines four authored errors.

from agent_cases import error_taxonomy_case

result = error_taxonomy_case()
assert result["retryable"] == ["rate_limit", "timeout"]
assert result["permanent"] == ["invalid_arguments", "permission_denied"]
assert result["blind_retry"] is False

Rate limit and timeout can retry within budget. Invalid arguments require a repaired proposal; permission denial stops and reports. The table does not describe every provider.

Design a typed tool result

Return success/failure, stable code, retryable flag, safe message, operation receipt and optional retry-after. Keep stack traces and secrets out of model-visible content. The orchestrator—not model prose—applies retry policy.

For write timeouts, outcome may be unknown. Query by idempotency key before retrying. Business errors such as duplicate request or closed account may be successful tool execution with a non-approved outcome.

Test each policy

Inject every code, exhaust retries, cancel during backoff and verify total budget. Check that a permanent failure cannot be transformed into a retryable one by a retrieved instruction.

The Generative & Agentic AI course connects typed errors to termination, runbooks and user-facing recovery.

Exercise

Define ten codes for one integration. Simulate each and assert attempts, final state, user message and side-effect count.

Continue learning

This article is part of the Agent workflows and state sequence. Use the neighbouring tasks when you need the prerequisite or the next application.

• Review the prerequisite or neighbouring task in Cancel a long-running agent without leaving orphan work.
• Continue with Agent memory: separate facts, preferences and temporary state.

Reference: Google API error model.