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 CalculateBackoff(attempt int) time.Duration
- func ClassifyModelError(err error) (retryable, rateLimited bool, retryAfter time.Duration)
- func ExtractHTTPStatusCode(err error) int
- func FormatError(err error) string
- func IsContextOverflowError(err error) bool
- func IsRetryableModelError(err error) bool
- func IsRetryableStatusCode(statusCode int) bool
- func ParseRetryAfterHeader(value string) time.Duration
- func SleepWithContext(ctx context.Context, d time.Duration) bool
- func WrapHTTPError(statusCode int, resp *http.Response, err error) error
- type ContextOverflowError
- 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.
const ( // MaxRetryAfterWait caps how long we'll honor a Retry-After header to prevent // a misbehaving server from blocking the agent for an unreasonable amount of time. MaxRetryAfterWait = 60 * time.Second )
Backoff and retry-after configuration constants.
Variables ¶
This section is empty.
Functions ¶
func CalculateBackoff ¶
CalculateBackoff returns the backoff duration for a given attempt (0-indexed). Uses exponential backoff with jitter.
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 ExtractHTTPStatusCode ¶
ExtractHTTPStatusCode attempts to extract an HTTP status code from the error. Checks in order: 1. Known provider SDK error types (Anthropic, Gemini) 2. Regex parsing of error message (fallback for OpenAI and others) Returns 0 if no status code found.
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 IsRetryableModelError ¶
IsRetryableModelError determines if an error should trigger a retry of the SAME model.
Retryable errors (retry same model with backoff): - Network timeouts - Temporary network errors - HTTP 5xx errors (server errors) - HTTP 529 (Anthropic overloaded) - HTTP 408 (request timeout)
Non-retryable errors (skip to next model in chain immediately): - Context cancellation - HTTP 429 (rate limit) - provider is explicitly rate limiting us - HTTP 4xx errors (client errors) - Authentication errors - Invalid request errors
The key distinction is: 429 means "you're calling too fast, slow down" which suggests we should try a different model, not keep hammering the same one.
func IsRetryableStatusCode ¶
IsRetryableStatusCode determines if an HTTP status code is retryable. Retryable means we should retry the SAME model with exponential backoff.
Retryable status codes: - 5xx (server errors): 500, 502, 503, 504 - 529 (Anthropic overloaded) - 408 (request timeout)
Non-retryable status codes (skip to next model immediately): - 429 (rate limit) - provider is explicitly telling us to back off - 4xx client errors (400, 401, 403, 404) - won't get better with retry
func ParseRetryAfterHeader ¶ added in v1.32.3
ParseRetryAfterHeader parses a Retry-After header value. Supports both seconds (integer) and HTTP-date formats per RFC 7231 §7.1.3. Returns 0 if the value is empty, invalid, or results in a non-positive duration.
func SleepWithContext ¶
SleepWithContext sleeps for the specified duration, returning early if context is cancelled. Returns true if the sleep completed, false if it was interrupted by context cancellation.
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 (*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