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 ¶
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. Context overflow gets a dedicated actionable message; all other errors pass through their original message.
func IsContextOverflowError ¶
IsContextOverflowError checks whether the error indicates the conversation context has exceeded the model's context window. It inspects both structured SDK error types and raw error message patterns.
Recognised patterns include:
- Anthropic 400 "prompt is too long: N tokens > M maximum"
- Anthropic 400 "max_tokens must be greater than thinking.budget_tokens" (emitted when the prompt is so large that max_tokens can't accommodate the thinking budget — a proxy for context overflow)
- OpenAI 400 "maximum context length" / "context_length_exceeded"
- Anthropic 500 that is actually a context overflow (heuristic: the error message is opaque but the conversation was already near the limit)
This function intentionally does NOT match generic 500 errors; callers that want to treat an opaque 500 as overflow must check separately with additional context (e.g., session token counts).
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
}
ContextOverflowError wraps an underlying error to indicate that the failure was caused by the conversation context exceeding the model's context window. This is used to trigger auto-compaction in the runtime loop instead of surfacing raw HTTP errors to the user.
func NewContextOverflowError ¶ added in v1.35.0
func NewContextOverflowError(underlying error) *ContextOverflowError
NewContextOverflowError creates a ContextOverflowError wrapping the given underlying error. Use this constructor rather than building the struct directly so that future field additions don't break callers.
func (*ContextOverflowError) Error ¶
func (e *ContextOverflowError) Error() string
func (*ContextOverflowError) Unwrap ¶
func (e *ContextOverflowError) Unwrap() 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