Error-Type Taxonomy: Transport, Request, Parsing, Model-Output, Tool-Loop
CoreIdentify the type of a Claude application error · Difficulty 2/5
Explanation
The Five Failure Buckets
Failures in a Claude application fall into recognizable buckets, and the bucket dictates the fix:
| Failure type | Where it lives | Signal |
|---|---|---|
| Transport/HTTP | Integration layer | 429 rate limit, 529/5xx overload, timeouts |
| Request error | Integration layer | 400 bad request, 401 auth, schema/max_tokens mistakes |
| Parsing/validation | Integration layer | Code throws when reading Claude's output (bad JSON, missing field) |
| Model-output error | Model output | Well-formed but *wrong*: hallucinated fact, missed instruction, wrong format |
| Tool-loop error | Integration ↔ model | Wrong tool chosen, malformed arguments, tool result not fed back correctly |
The Core Discipline
Three of the five buckets live squarely in the integration layer (your code, request, and parsing), one lives in the model's actual output, and tool-loop errors straddle both. The discipline that matters most: don't "fix" the prompt when the bug is in your code, and don't patch code when the model output is the problem. Misclassifying the bucket sends the fix to the wrong layer entirely.
Common exam traps
- A crash while reading the response (e.g.,
json.loadsfails) is an integration-layer parsing bug, not a model quality problem -- the model may have returned reasonable text your parser didn't tolerate. Add defensive parsing before assuming the model is wrong. - Treating a well-formed-but-wrong answer as a parsing bug, or a genuine parsing exception as a sign the model hallucinated -- the fix lives wherever the failure signal actually points, not wherever is easiest to blame.
Key Takeaways
- Five recognizable failure buckets: transport/HTTP, request error, parsing/validation, model-output, and tool-loop
- Transport, request, and parsing errors live in the integration layer; model-output errors are well-formed but wrong
- Tool-loop errors straddle the integration layer and the model's tool choices/arguments
- Don't fix the prompt when the bug is in your code, and don't patch code when the model output is the problem
- A JSON parse crash on a successful response is an integration-layer bug, not evidence the model is wrong
Glossary Terms
The practice of returning structured, actionable error information from tools rather than generic error strings. Well-designed error responses include: error type, what went wrong, what Claude should try next. Prevents Claude from retrying the same failing approach repeatedly.
The five recognizable buckets a Claude application failure falls into -- transport/HTTP (429/529/5xx), request error (400/401), parsing/validation (a code-level exception reading the response), model-output error (well-formed but wrong content), and tool-loop error (wrong tool, malformed arguments, or a mis-fed tool_result). The bucket a failure falls into dictates the correct fix, and misclassifying it sends the fix to the wrong layer.
A field in the Claude API response indicating why the model stopped generating. Values: 'end_turn' (natural completion), 'max_tokens' (hit limit), 'stop_sequence' (hit custom stop), 'tool_use' (wants to call a tool). The primary signal for controlling agentic loops.
A debugging technique for multi-step agents and workflows: logging every model call, tool call and its arguments, tool result, and intermediate message, then walking that sequence to find the earliest step that deviated -- rather than debugging only the final failing output.
Related Concepts