Documentation
¶
Overview ¶
Package errors provides agent-specific error types and classification for intelligent retry/recovery logic.
This package defines a taxonomy of errors that the agent can use to make informed decisions about how to handle failures. Unlike the generic StructuredError in pkg/utils, these errors are specifically designed to support the agent's retry logic and recovery strategies.
Categories:
- CategoryTransient: Temporary failures (network, timeout, provider overload) - retryable
- CategoryRateLimited: Rate limit/quota exhaustion - retryable with backoff
- CategorySecurity: Security violations (blocked commands, unauthorized access) - not retryable
- CategoryInvalidInput: Invalid parameters, malformed requests - not retryable
- CategoryProvider: Provider-specific failures (auth, model not found) - depends on cause
- CategoryContext: Context window exceeded, compaction needed - retryable after compaction
- CategoryPermanent: Non-recoverable errors - not retryable
Example usage:
err := errors.NewTransientError("network timeout", originalErr)
if errors.IsRetryable(err) {
// Retry with backoff
}
if errors.IsContextError(err) {
// Trigger conversation compaction
}
Index ¶
- func IsContextError(err error) bool
- func IsInvalidInput(err error) bool
- func IsPermanent(err error) bool
- func IsProviderError(err error) bool
- func IsRateLimited(err error) bool
- func IsRetryable(err error) bool
- func IsSecurity(err error) bool
- func IsTransient(err error) bool
- type AgentError
- func NewContextError(message string, cause error) *AgentError
- func NewInvalidInputError(message string, cause error) *AgentError
- func NewPermanentError(message string, cause error) *AgentError
- func NewProviderError(message string, cause error, provider, model string) *AgentError
- func NewRateLimitError(message string, cause error, provider string) *AgentError
- func NewSecurityError(message string, cause error) *AgentError
- func NewTransientError(message string, cause error) *AgentError
- func WrapWithCategory(err error, category ErrorCategory, message string) *AgentError
- func (e *AgentError) Error() string
- func (e *AgentError) GetMetadata(key string) string
- func (e *AgentError) Unwrap() error
- func (e *AgentError) WithMetadata(key, value string) *AgentError
- func (e *AgentError) WithModel(model string) *AgentError
- func (e *AgentError) WithProvider(provider string) *AgentError
- type ErrorCategory
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsContextError ¶
IsContextError checks if an error is in the Context category.
func IsInvalidInput ¶
IsInvalidInput checks if an error is in the InvalidInput category.
func IsPermanent ¶
IsPermanent checks if an error is in the Permanent category.
func IsProviderError ¶
IsProviderError checks if an error is in the Provider category.
func IsRateLimited ¶
IsRateLimited checks if an error is in the RateLimited category.
func IsRetryable ¶
IsRetryable checks if an error is retryable. Returns true if the error is an AgentError with Retryable=true.
func IsSecurity ¶
IsSecurity checks if an error is in the Security category.
func IsTransient ¶
IsTransient checks if an error is in the Transient category.
Types ¶
type AgentError ¶
type AgentError struct {
Category ErrorCategory
Message string
Cause error
Retryable bool
Metadata map[string]string
}
AgentError represents a structured error with classification for agent retry logic. It implements the error interface and supports error unwrapping for compatibility with errors.Is() and errors.As().
func NewContextError ¶
func NewContextError(message string, cause error) *AgentError
NewContextError creates a retryable context error. Should be retried after conversation compaction.
func NewInvalidInputError ¶
func NewInvalidInputError(message string, cause error) *AgentError
NewInvalidInputError creates a non-retryable invalid input error. Examples: invalid parameters, malformed requests.
func NewPermanentError ¶
func NewPermanentError(message string, cause error) *AgentError
NewPermanentError creates a non-retryable permanent error. Examples: non-recoverable failures, configuration errors.
func NewProviderError ¶
func NewProviderError(message string, cause error, provider, model string) *AgentError
NewProviderError creates a provider-specific error. Retryability depends on the underlying cause. Includes provider and model info. For auth errors, this is not retryable. For model not found, not retryable. For provider overload, may be retryable.
func NewRateLimitError ¶
func NewRateLimitError(message string, cause error, provider string) *AgentError
NewRateLimitError creates a retryable rate limit error. Includes provider information for key rotation decisions.
func NewSecurityError ¶
func NewSecurityError(message string, cause error) *AgentError
NewSecurityError creates a non-retryable security error. Examples: blocked commands, unauthorized access.
func NewTransientError ¶
func NewTransientError(message string, cause error) *AgentError
NewTransientError creates a retryable transient error for temporary failures. Examples: network timeout, connection reset, provider overload.
func WrapWithCategory ¶
func WrapWithCategory(err error, category ErrorCategory, message string) *AgentError
WrapWithCategory wraps an existing error with a specific category and message. The original error is preserved as the cause, maintaining the error chain.
func (*AgentError) Error ¶
func (e *AgentError) Error() string
Error returns a formatted error message. If a cause is present, it includes the wrapped error. The format is:
[Category] message: cause
If no cause is present:
[Category] message
func (*AgentError) GetMetadata ¶
func (e *AgentError) GetMetadata(key string) string
GetMetadata returns the value for a metadata key, or empty string if not found.
func (*AgentError) Unwrap ¶
func (e *AgentError) Unwrap() error
Unwrap returns the underlying error for compatibility with errors.Is and errors.As.
func (*AgentError) WithMetadata ¶
func (e *AgentError) WithMetadata(key, value string) *AgentError
WithMetadata adds or updates a metadata key-value pair.
func (*AgentError) WithModel ¶
func (e *AgentError) WithModel(model string) *AgentError
WithModel sets the model in metadata.
func (*AgentError) WithProvider ¶
func (e *AgentError) WithProvider(provider string) *AgentError
WithProvider sets the provider in metadata.
type ErrorCategory ¶
type ErrorCategory int
ErrorCategory represents the classification of an error for retry/recovery logic.
const ( // CategoryTransient indicates a temporary failure that should be retried. // Examples: network timeout, connection reset, 502 gateway errors. CategoryTransient ErrorCategory = iota // CategoryRateLimited indicates rate limit or quota exhaustion. // Should be retried with exponential backoff and key rotation if available. CategoryRateLimited // CategorySecurity indicates a security violation. // Should NOT be retried. Examples: blocked commands, unauthorized access. CategorySecurity // CategoryInvalidInput indicates invalid parameters or malformed requests. // Should NOT be retried without fixing the input. CategoryInvalidInput // CategoryProvider indicates provider-specific failures. // Retryability depends on the underlying cause. Examples: auth errors, model not found. CategoryProvider // CategoryContext indicates context window exceeded. // Should be retried after conversation compaction. CategoryContext // CategoryPermanent indicates non-recoverable errors. // Should NOT be retried. CategoryPermanent )
func GetCategory ¶
func GetCategory(err error) (ErrorCategory, bool)
GetCategory extracts the error category from an AgentError. Returns the category and true if the error is an AgentError, or zero and false otherwise.
func (ErrorCategory) String ¶
func (c ErrorCategory) String() string
String returns a human-readable representation of the error category.
Source Files