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 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 SleepWithContext(ctx context.Context, d time.Duration) bool
- type ContextOverflowError
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 CalculateBackoff ¶
CalculateBackoff returns the backoff duration for a given attempt (0-indexed). Uses exponential backoff with jitter.
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
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
Source Files