failure

package
v1.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 11, 2026 License: AGPL-3.0 Imports: 1 Imported by: 0

Documentation

Overview

Package failure owns normalized inference failure semantics.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Failure

type Failure struct {
	// contains filtered or unexported fields
}

Failure separates a client-safe message from provider and cause details.

func New

func New(kind Kind, safeMessage string, retryable bool, provider ProviderDetails, cause error) *Failure

New constructs one normalized failure.

func (*Failure) Error

func (f *Failure) Error() string

Error returns only the client-safe failure text.

func (*Failure) Kind

func (f *Failure) Kind() Kind

Kind returns the stable failure class.

func (*Failure) ProviderDetails

func (f *Failure) ProviderDetails() ProviderDetails

ProviderDetails returns a copy of the provider-only evidence.

func (*Failure) Retryable

func (f *Failure) Retryable() bool

Retryable reports whether policy can retry the logical attempt.

func (*Failure) SafeMessage

func (f *Failure) SafeMessage() string

SafeMessage returns text that a protocol adapter can expose.

func (*Failure) StateScope added in v1.0.3

func (f *Failure) StateScope() StateScope

StateScope returns the durable scope proved by normalized provider evidence. An empty scope is deliberately non-mutating.

func (*Failure) Unwrap

func (f *Failure) Unwrap() error

Unwrap returns the internal cause for errors.Is and errors.As.

type Kind

type Kind string

Kind identifies a stable failure class.

const (
	// Validation identifies invalid client input.
	Validation Kind = "validation"
	// Authentication identifies invalid credentials.
	Authentication Kind = "authentication"
	// Permission identifies an unauthorized action.
	Permission Kind = "permission"
	// Quota identifies an exhausted non-burst provider allocation.
	Quota Kind = "quota"
	// Billing identifies an account payment or credit failure.
	Billing Kind = "billing"
	// RateLimit identifies provider or gateway throttling.
	RateLimit Kind = "rate_limit"
	// NotFound identifies an absent model or provider resource.
	NotFound Kind = "not_found"
	// ContextLimit identifies input that exceeds a model context window.
	ContextLimit Kind = "context_limit"
	// ContentBlocked identifies a provider content-policy rejection.
	ContentBlocked Kind = "content_blocked"
	// ProviderUnavailable identifies a provider that responded and cannot
	// accept the attempt.
	ProviderUnavailable Kind = "provider_unavailable"
	// Unreachable identifies a provider that returned no response at all:
	// the request left the gateway and the transport failed before any
	// provider verdict came back.
	Unreachable Kind = "unreachable"
	// Timeout identifies an elapsed request deadline.
	Timeout Kind = "timeout"
	// Canceled identifies caller cancellation.
	Canceled Kind = "canceled"
	// Internal identifies a gateway implementation failure.
	Internal Kind = "internal"
)

type ProviderDetails

type ProviderDetails struct {
	Provider   string
	StatusCode int
	Type       string
	Code       string
	Message    string
	StateScope StateScope
}

ProviderDetails retains provider evidence for internal policy and diagnostics.

type StateScope added in v1.0.3

type StateScope string

StateScope identifies the durable runtime state that provider evidence can change. ScopeNone keeps request-local failures out of durable state.

const (
	// ScopeNone makes no durable provider-state change.
	ScopeNone StateScope = ""
	// ScopeCredential changes only the selected credential material version.
	ScopeCredential StateScope = "credential"
	// ScopeOffering changes only the exact provider model offering.
	ScopeOffering StateScope = "offering"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL