Modulo 5.9 Error Handling - Claude Code Deep Dive

1

🏗️ Four Error Stack Layers

Layer 1: Typed Error Classes

Vocabulario de excecoes nomeadas por dominio de falha -- ClaudeError, AbortError, ShellError, ConfigParseError

Layer 2: API Retry Engine

Backoff exponencial, fallback 529, refresh auth, overflow de contexto

Layer 3: Terminal Error Overlay

Trecho de source inline com linha de crash destacada

Layer 4: Conversation Recovery

Resume de sessoes interrompidas/mid-turn

2

📚 The Error Taxonomy

Classe	Proposito	Campos-chave
AbortError	Cancelamento por usuario (Esc/Ctrl-C)	name = 'AbortError'
ShellError	Comando shell exit nao-zero	stdout, stderr, code, interrupted
ConfigParseError	Arquivo config corrupto/ilegivel	filePath, defaultConfig
TelemetrySafeError_I_VERIFIED...	Seguro para telemetria	telemetryMessage

isAbortError -- Three-Way Check

Checa instanceof AbortError, instanceof APIUserAbortError (SDK) e e.name === 'AbortError' (DOMException). Necessario porque minificacao mangle nomes de construtor.

3

🔄 API Retry Engine

withRetry e um async generator que encapsula cada chamada API Anthropic. Implementa retry sofisticado:

// Backoff exponencial com jitter +-25%
baseDelay = min(500ms * 2^(attempt-1), 32s)
jitter = random() * 0.25 * baseDelay
delay = baseDelay + jitter

529 (Overloaded) -- Background queries bail imediatamente. Apos 3 consecutivos em Opus, fallback para modelo configurado.

Context Overflow -- Parseia contagem de tokens do erro 400 e ajusta maxTokens automaticamente. Floor de 3K tokens.

Unattended Mode -- CLAUDE_CODE_UNATTENDED_RETRY=1 habilita retry indefinido em 429/529 com backoff max 5min e cap total de 6h.

4

🛠️ Tool Error Formatting

Falhas de tools requerem formatacao para dois consumidores: terminal (usuario) e modelo (em blocos tool_result).

Cap de 10.000 caracteres com center-truncation: mantem 5K head + 5K tail. Protege budget de contexto de outputs grandes de compilador.

Zod errors -> LLM-friendly: Caminhos formatados como todos[0].activeForm e tipos expected/received especificados para habilitar auto-correcao do modelo.

5

💻 Terminal Error Overlay

Quando excecoes nao tratadas atingem o Ink render tree, ErrorOverview exibe overlay formatado com localizacao de crash e contexto de source inline:

Parseia primeiro stack frame para file + line + column (StackUtils)
Le source file sincronamente (readFileSync)
Renderiza: linha de crash destacada em vermelho, linhas vizinhas dim

readFileSync justificado: Componente renderiza sincronamente dentro do Ink reconciler. Como e o path de erro (processo ja quebrado), sync I/O e aceitavel.

6

🔧 Conversation Recovery Pipeline

Pipeline de 4 estagios de deserializacao:

Stage 1: Legacy migration -- transforma tipos antigos de attachment

Stage 2: Strip bad permission modes -- remove valores invalidos

Stage 3: Filter invalid messages -- remove tool_use orfaos, thinking-only, whitespace-only

Stage 4: Interrupt detection -- classifica como none / interrupted_prompt / interrupted_turn

interrupted_turn converte para interrupted_prompt injetando mensagem sintetica "Continue from where you left off." com isMeta: true, unificando ambos os tipos de interrupcao.

7

🗺️ End-to-End Error Flows

Runtime Errors

Tool falha -> formatError() -> tool_result block ao modelo + display no terminal

API Errors

API retorna erro -> withRetry() -> backoff + SystemAPIErrorMessage -> (exauriu) CannotRetryError -> logError() + ErrorOverview

Session Recovery

Processo morto mid-turn -> --continue/--resume -> pipeline 4-stage -> detectTurnInterruption() -> auto-resume

📋 Resumo do Modulo

✅Cada dominio de falha tem classe de erro typed dedicada, habilitando instanceof checks que sobrevivem minificacao

✅withRetry lida com 10+ modos de falha: 529 model fallback, context overflow auto-adjust, OAuth refresh, backoff exponencial com jitter

✅Background queries bail imediatamente em 529 -- retry amplificaria cascata de capacidade

✅Tool errors truncam a 10K chars (5K head + 5K tail) antes de enviar ao modelo

✅Recovery roda pipeline de 4 stages limpando transcripts quebrados e injetando mensagens sinteticas para auto-resume

✅TelemetrySafeError usa verbosidade deliberada como funcao de revisao de codigo -- devs devem confirmar que dados senssiveis nao estao na mensagem