Erros normalizados

Cada SDK levanta exceções diferentes. A jangada traduz tudo para uma hierarquia única via errors.classify(), com status_code quando disponível. Nenhum erro nativo de SDK escapa da fronteira dos adapters.

from jangada_ai import LLM, errors

try:
    LLM("openai", "modelo-inexistente").complete("oi")
except errors.NotFoundError as e:
    print(e.status_code)   # 404
except errors.LLMError as e:
    print("falha genérica:", e)

Hierarquia (resumo)

Todas herdam de errors.LLMError. As principais categorias:

Conjuntos usados pela política

• errors.TRANSIENT — o que dispara retry com backoff (rate limit, timeout, conexão, 5xx).
• errors.DEFAULT_FAILOVER — o que dispara fallback (os transitórios + 404 + OutputValidationError). Não inclui auth nem bad_request por padrão.

Você pode customizar retry_on= e backoff_on= por LLM — veja Retry e fallback.

O que mudou na 1.9.0

• Mais status HTTP mapeados: 408 → APITimeoutError e 409 → ServerError (ambos transitórios, entram no retry); 413 → BadRequestError.
• Recusas e respostas vazias viram erro normalizado. Resposta sem choices, recusa da OpenAI no parse (parsed=None) ou Claude sem tool_use no parse levantam OutputValidationError / ServerError — que entram no failover — em vez de IndexError/StopIteration crus.
• Saída cortada no parse da OpenAI (LengthFinishReasonError) vira TruncatedError, com a dica de aumentar max_tokens.
• Gemini com prompt bloqueado por safety levanta BadRequestError (sem retry nem fallback — é determinístico), em vez de um ServerError "transitório".
• classify(e, provider, *, request=False): com request=True, um ValidationError do Pydantic vindo da montagem da requisição (SDKs como google-genai e mistralai validam o request) vira BadRequestError, não OutputValidationError — não dispara mais failover para outro modelo por um extra= inválido. Os adapters já usam isso nos caminhos que não são parse.