Documentation
¶
Overview ¶
Package modelerrors provides error classification utilities for LLM model providers. It determines whether errors are retryable, identifies context window overflow conditions, extracts HTTP status codes from various SDK error types, and computes exponential backoff durations.
Index ¶
- Constants
- func ClassifyModelError(err error) (retryable, rateLimited bool, retryAfter time.Duration)
- func FormatError(err error) string
- func IsContextOverflowError(err error) bool
- func WrapHTTPError(statusCode int, resp *http.Response, err error) error
- type ContextOverflowError
- type OverflowKind
- type StatusError
Constants ¶
const ( // DefaultRetries is the default number of retries per model with exponential // backoff for retryable errors (5xx, timeouts). 2 retries means 3 total attempts. // This handles transient provider issues without immediately failing over. DefaultRetries = 2 // DefaultCooldown is the default duration to stick with a fallback model // after a non-retryable error before retrying the primary. DefaultCooldown = 1 * time.Minute )
Default fallback configuration.
Variables ¶
This section is empty.
Functions ¶
func ClassifyModelError ¶ added in v1.32.3
ClassifyModelError classifies an error for the retry/fallback decision.
If the error chain contains a *StatusError (wrapped by provider adapters), its StatusCode and RetryAfter fields are used directly — no provider-specific imports needed in the caller.
Returns:
- retryable=true: retry the SAME model with backoff (5xx, timeouts)
- rateLimited=true: it's a 429 error; caller decides retry vs fallback based on config
- retryAfter: Retry-After duration from the provider (only set for 429)
When rateLimited=true, retryable is always false — the caller is responsible for deciding whether to retry (when no fallback is configured) or skip to the next model (when fallbacks are available).
func FormatError ¶
FormatError returns a user-friendly error message for model errors. Overflow errors get a kind-specific actionable message; other errors fall through to err.Error(). For HTTP errors that text comes from *StatusError, which itself extracts structured provider details (see parseProviderError).
The messages are provider-agnostic by design: docker-agent supports many LLM providers and the cap that triggered the rejection is a deployment detail of the provider, not something the user can act on by name.
func IsContextOverflowError ¶
IsContextOverflowError reports whether err indicates the conversation exceeded a provider-side limit (token window, wire size, or media size). Use OverflowKindOf to distinguish the three shapes.
func WrapHTTPError ¶ added in v1.32.3
WrapHTTPError wraps err in a *StatusError carrying the HTTP status code and parsed Retry-After header from resp. Returns err unchanged if statusCode < 400 or err is nil. Pass resp=nil when no *http.Response is available.
Types ¶
type ContextOverflowError ¶
type ContextOverflowError struct {
Underlying error
Kind OverflowKind
}
ContextOverflowError wraps an underlying error to indicate that the failure was caused by the conversation context exceeding some provider-side limit. This is used to trigger auto-compaction in the runtime loop instead of surfacing raw HTTP errors to the user.
Kind classifies the specific shape of the overflow (OverflowKindTokens by default for backwards compatibility). Use NewContextOverflowError to have it set automatically by classification, or build the struct directly to force a Kind.
func NewContextOverflowError ¶ added in v1.35.0
func NewContextOverflowError(underlying error) *ContextOverflowError
NewContextOverflowError creates a ContextOverflowError wrapping the given underlying error. The Kind is inferred from the underlying error via [classifyOverflow]; if classification yields no result, Kind defaults to OverflowKindTokens (the historical behaviour). Use this constructor rather than building the struct directly so future field additions don't break callers.
func (*ContextOverflowError) Error ¶
func (e *ContextOverflowError) Error() string
func (*ContextOverflowError) Unwrap ¶
func (e *ContextOverflowError) Unwrap() error
type OverflowKind ¶ added in v1.62.0
type OverflowKind string
OverflowKind classifies the cause of a context overflow, so the runtime and UI can react differently to each shape.
- OverflowKindTokens: the accumulated conversation exceeds the model's context window. Token-count rejection. Compaction can usually help.
- OverflowKindWire: the request body exceeds the provider's wire-level limit (e.g. Anthropic's 32 MB cap, gateway 413s). Compaction usually CANNOT help because the offending single turn still has to be sent.
- OverflowKindMedia: an image, PDF, or similar attachment in the conversation exceeds the provider's media constraints (size, page count, dimensions).
const ( OverflowKindTokens OverflowKind = "tokens" OverflowKindWire OverflowKind = "wire" OverflowKindMedia OverflowKind = "media" )
func OverflowKindOf ¶ added in v1.62.0
func OverflowKindOf(err error) OverflowKind
OverflowKindOf returns the OverflowKind of err, or "" if it isn't an overflow error. If err is already wrapped in a *ContextOverflowError with a non-empty Kind, that Kind is returned; otherwise classification runs on the unwrapped error.
type StatusError ¶ added in v1.32.3
type StatusError struct {
// StatusCode is the HTTP status code from the provider's API response.
StatusCode int
// RetryAfter is the parsed Retry-After header duration. Zero if absent.
RetryAfter time.Duration
// Err is the original error from the provider SDK.
Err error
}
StatusError wraps an HTTP API error with structured metadata for retry decisions. Providers wrap SDK errors in this type so the retry loop can use errors.As to extract status code and Retry-After without importing provider-specific SDKs.
func (*StatusError) Error ¶ added in v1.32.3
func (e *StatusError) Error() string
func (*StatusError) Unwrap ¶ added in v1.32.3
func (e *StatusError) Unwrap() error
Source Files