Expand description
The typed provider failure family and its retry classification (spec §24, §20.7).
Every adapter maps its vendor errors into a ProviderError: a ProviderErrorKind
with its classification payload, the provider and model keys, and an optional short
code. Nothing from the wire appears in one: Display and Debug render the kind, the
keys and a code ErrorCode::new sanitized, never a body, a header, a prompt, user text
or a secret (spec §25.2).
ProviderError::retry_class says what the caller may do next. Whether it may retry at
all is FallbackStage’s to decide (I17).
RetryClass | Meaning |
|---|---|
Retry | The same provider may be tried again after a backoff. |
RetryAfter | The same provider may be tried again, but only after the delay the provider asked for. |
Fallback | This provider will keep failing; move to the next candidate that satisfies the same requirements. |
Fatal | Neither retrying nor falling back can help; fail the stage. |
Three kinds look alike from a status code and are not; the conformance suite has a row for each:
| Looks like | Actually | Why it matters |
|---|---|---|
Authentication | CredentialExpired | A wrong key stays wrong; an expired token works again after a refresh. Providers that issue short-lived credentials (Vertex AI bearer tokens, Bedrock session credentials) fail this way routinely. |
RateLimited | QuotaExhausted | A rate limit clears by waiting; a quota or an empty balance does not, and several providers report both with HTTP 429. |
InvalidRequest | ContextOverflow | Both arrive as HTTP 400; only one is fixed by shrinking the prompt. |
Structs§
- Error
Code - A short, sanitized machine code an adapter attaches to a failure.
- Provider
Detail - The endpoint’s own sentence about why it refused, sanitized.
- Provider
Error - A normalized provider failure.
Enums§
- Provider
Error Kind - The failure families an adapter maps its vendor errors into.
- Retry
Class - What the caller may do after a failure (spec §20.7).
Constants§
- MAX_
ERROR_ CODE_ LEN - Maximum length of a sanitized
ErrorCode, in bytes. - MAX_
ERROR_ DETAIL_ LEN - Longest sanitized
ProviderDetail, in bytes.