What kind of failure is it
Reporting a failure rather than hiding it is half the job. What turns that report into the right next move is saying which kind of failure it was, because "it failed" on its own tells you nothing about what to do. Different failures want opposite responses, and a system that treats them all the same will retry the ones that can never succeed and give up on the ones a moment's wait would have fixed. The wider set of decisions this sits inside is Ways to build an AI agent.
Say it another way
A ticket comes back from the kitchen unfilled, and a good waiter knows there are only a few reasons, each meaning a different move. The oven was briefly jammed, so re-fire the same ticket. The order was written illegibly, so rewrite it and send it again. The dish is off the menu, so go and tell the guest kindly rather than keep asking. The dish is chef’s-table only and not his to serve, so fetch the manager. Same empty ticket, four different right moves. A waiter who only says “it came back” leaves you to guess which.
Doing this with Claude Code
When you build a step that can fail, have it say enough about the failure for the next move to be obvious.
Have the failure name its kind. A passing blip, a bad request, a firm no or something off-limits are different things wanting different responses, so have the step say which it is rather than a flat “failed”.
Say whether it is worth retrying. Mark the passing problems as worth another attempt and the settled ones as not, so the system retries the blips and never hammers a rule that will not move.
Carry the reason on a no. When a rule blocks something, return the why in words a person can hear, so a refusal can be explained rather than landing as a blank wall.
Keep the shape the same every time. Have failures come back in one consistent form, the kind, whether to retry and a plain description, so whatever reads them always knows where to look.
Common questions
- Why is "it failed" not enough?
On its own it tells you nothing about what to do next. A system that treats every failure the same will retry the ones that can never succeed, and give up on the ones a moment's wait would have fixed. - What are the kinds of failure?
Roughly four, and each points to a different move: something briefly broke, the request itself was wrong, a rule said no, or the system is simply not allowed to do it. - What does a passing blip need?
A timeout or a brief outage is worth trying again, because the same request is likely to work the second time. Nothing needs fixing before the retry. - What does a bad request need?
A malformed request will fail the same way until it is corrected, so the fix comes first and the retry after. Retrying it unchanged just repeats the failure. - What does a rule saying no need?
A refund outside the returns window will never change its answer however many times you ask, so the honest no is explained to the person rather than retried. - What does something off-limits need?
Work the system is not permitted to do is handed up to someone who can do it, rather than attempted or refused outright. - If I carry one thing with a failure, what should it be?
Whether it is even worth trying again. Saying so plainly stops a system hammering a wall it will never get through, and stops it abandoning the one case a brief wait would have resolved. - What should a genuine no carry with it?
The reason. "Cannot do that" leaves the person stranded, where "that order is past the thirty-day return window, but here is what I can offer instead" is a refusal they can act on.
Back to For developers. The craft around it is Working with AI.