A failure has a kind¶
Decided in the release after 1.22.0.
Context and problem statement¶
ADR-0001 names six outcomes, and they are deliberately coarse: a fallback policy is a short
match. But two policies cannot be written on them. A retry policy cannot tell a full queue
(rate_limited, back in seconds) from a spent quota (quota, back tomorrow): both were
unavailable. A health tracker could not tell a model outage from a caller's bug: an exception
the classifier did not recognise (a KeyError in a validator) was unavailable, so the backend
was marked down for the caller's mistake. And a reply cut by the token ceiling was ok whenever
the cut text happened to parse.
Every consumer re-derived the detail from provider strings: a 429 with "budget" in the body, a
"Please retry in 8h26m" hint, a finish_reason of length.
Decision drivers¶
- Outcomes stay coarse: existing
matchstatements with a default arm keep compiling. - The detail is classified once, by one table every adapter shares, from the exception chain and what the wire showed, with no response body in the reason.
- A bug is not an outage. A cut reply is not a whole one.
Decision¶
Outcomegains exactly one member,refused: the model or its provider declined.Failure(kind, outcome, retryable, retry_after_s, status, provider_code, phase, in_stream, reason), withoutcomeandretryablederived fromkind(OUTCOME_FOR,RETRYABLE). Eighteen kinds:gated; underunavailablerate_limited,quota,overloaded,server,timeout,transport,auth,not_found,malformed_response,caller_limit; underrequest_faultbad_request,context_overflow,unsupported,internal;truncated;invalid_output;refused.- One classification order (
adapters._classify.classify_core): extra classifiers first (a gateway's knowledge), then a gated type in the chain, an HTTP client'sInvalidURLorUnsupportedProtocolin the chain (internal: the caller's URL, nothing was sent), the framework's categories (pydantic-ai'sModelAPIErrorclasses, walked over the whole chain), a context-overflow code or message, the HTTP status, a transport error, thenmalformed_responsewhen a provider client raised while reading a response that arrived (a status is known), and otherwiseinternal. With no exception, a refusal orcontent_filterfinish isrefusedand alengthfinish istruncated. An exception group (a fallback chain's) is classified member by member, and its worst member names the call (SEVERITY). - Behaviour fix: a
lengthfinish istruncatedon the success path too. The cut value is kept on the result;Role.accept_truncated/GenRequest.accept_truncatedrestoreokwith aCallWarning. - Behaviour fix: a caller's bug is
internal, underrequest_fault, never retried and never counted against a backend. It is reported asllm_call_internal_errorwith its traceback. Who raised decides: an exception whose innermost owning frame is a provider client (PROVIDER_MODULES:pydantic_ai.models,openai,httpx,httpx2,httpcore) is that provider's malformed reply (malformed_response,unavailable, retryable), as is a 200 withchoices: [], but only once a response arrived: with no status nothing was parsed, so it isinternal. A caller's configuration isinternalwherever it is raised: pydantic-ai'sUserError(an output mode the model lacks) and an HTTP client'sInvalidURL/UnsupportedProtocol(a base URL no client can send); none of them sends a request. pydantic-ai'sUsageLimitExceeded, an application'sRunCancelledandConcurrencyLimitExceeded(the agent's own queue is full) arecaller_limit(unavailable, not retryable: a limit the caller set does not lift within a backoff, and it says nothing of the backend's health). All three wereunavailablein 1.x and stay so. adapters.litellm_proxy.classify_gatewaynames a 429 that no wait clears (a budget, a per-day limit, a provider retry hint over two minutes)quota; a parallel-limit 429 staysrate_limitedwith the server'sRetry-After.- The pydantic-ai floor is 2.62, the first release with every category class the table reads.
Considered options¶
- Split
unavailableinto finer outcomes. Every consumer'smatchwould need new arms, and most policies only need the coarse split. The detail belongs inkind. - Keep classifying a bug as
unavailable. That is the failure mode this ADR removes: a validator bug took a healthy backend out of rotation. - Classify by provider strings in each adapter. The reranker, the embedder and the generator
would drift. One table, with an
extrahook for gateway knowledge, keeps them equal. - Retry, deadlines and fallback here. They read
kindandretryablebut are a separate decision (the next row on the critical path).
Consequences¶
- A retry policy reads
failure.retryableandfailure.retry_after_s; the embedder's own retry now does, soauth,not_found,quotaandinternalare no longer retried. - A consumer's
matchwith a default arm keeps compiling; an exhaustivematchmust addrefused(a type checker names the missing arm). - A caller that relied on a cut reply being
oksetsaccept_truncated.