Diagnóstico útil começa classificando a falha
Timeout, indisponibilidade de modelo, teste quebrado e drift de contexto pedem respostas diferentes.
Nem todo erro pede retry
O runtime do Giorgio distingue falhas transitórias, falhas de implementação e perda de validade do contexto. Um timeout ou rate limit pode justificar retry; um teste quebrado pede reparo; drift de contexto pode exigir invalidar etapas construídas sobre uma base que mudou.
Classificações que mudam a ação
- MODEL_UNAVAILABLE, TIMEOUT e RATE_LIMIT: tratar como indisponibilidade transitória.
- TEST_FAILURE, SYNTAX_ERROR, TYPE_ERROR e RUNTIME_ERROR: reparar a implementação.
- BASE_DRIFT ou CONTEXT_DRIFT: revalidar o que dependia da base anterior.
Uma mensagem de erro precisa orientar
Mostrar apenas “não foi possível concluir” esconde a informação mais útil. O diagnóstico deveria dizer o tipo provável de falha, a evidência disponível e a próxima ação segura.
O contrato escondido em Falhas diferentes exigem recuperações diferentes
Timeout, rate limit, erro de sintaxe, falha de teste, drift de base e violação de contrato podem produzir a mesma frase “não foi possível concluir”, mas pedem respostas totalmente diferentes. Classificar cedo evita retries inúteis.
- causa raiz vem antes do fallback
- mudança não quebra subsistemas fora do escopo
- logs e códigos permitem reproduzir a falha
Falha específica: Falhas diferentes exigem recuperações diferentes
O anti-padrão é tratar qualquer 5xx como motivo para repetir o mesmo request. Isso consome quota, mascara causa raiz e pode multiplicar efeitos colaterais.
Evidência que fecha Falhas diferentes exigem recuperações diferentes
Um diagnóstico acionável informa classe, superfície afetada, se é retryable, qual evidência existe e qual próximo passo muda o estado do problema.
Falha que esse desenho evita como gate
Em “Diagnóstico útil começa classificando a falha”, o ponto técnico que fecha a análise é tratar ownership, recuperação e observabilidade como parte do mesmo contrato. A implementação deixa de ser convincente quando uma dessas dimensões existe só no texto, mas não aparece no comportamento verificável do produto.
- definir o estado esperado antes da ação
- observar o efeito real e registrar a evidência
- se o gate falhar, reparar a causa antes de ampliar o escopo
