Skip to content

errors.md

Latest commit

 

History

History
190 lines (154 loc) · 6.8 KB

errors.md

File metadata and controls

190 lines (154 loc) · 6.8 KB
Raw

Errors And Cancellation

Sigma errors are ordinary Go errors with sentinel support through errors.Is and typed detail through errors.As.

Common Sentinels

  • sigma.ErrNoProvider
  • sigma.ErrModelNotFound
  • sigma.ErrCredentialUnavailable
  • sigma.ErrAborted
  • sigma.ErrContextOverflow
  • sigma.ErrToolValidation
  • sigma.ErrProviderResponse
  • sigma.ErrInvalidOptions
  • sigma.ErrRetryAfterExceedsMaxDelay

The package error type, *sigma.Error, carries an ErrorCode, provider, model, and wrapped cause where available.

final, err := client.Complete(ctx, model, req)
if errors.Is(err, sigma.ErrModelNotFound) {
	return err
}
_ = final

Provider Errors

HTTP and provider failures should surface as *sigma.ProviderError and match sigma.ErrProviderResponse:

var providerErr *sigma.ProviderError
if errors.As(err, &providerErr) {
	log.Println(providerErr.Provider, providerErr.StatusCode, providerErr.RequestID)
}

ProviderError redacts body previews, request IDs, headers, and known secret shapes before formatting. ProviderError.Diagnostic returns safe-to-log context for an assistant message that ended with StopReasonError.

Classified Provider Errors

Use sigma.ClassifyError when an application needs stable retry or recovery decisions without parsing provider-specific error strings:

classification := sigma.ClassifyError(err)
switch classification.Class {
case sigma.ErrorClassContextOverflow:
	// Compact context and retry once.
case sigma.ErrorClassRateLimited, sigma.ErrorClassTransient:
	if classification.RetryHint.Retryable {
		time.Sleep(classification.RetryHint.After)
	}
case sigma.ErrorClassAuth, sigma.ErrorClassQuota, sigma.ErrorClassBilling:
	// Surface an account or credential action to the caller.
}

Structured provider codes take precedence over message text, except that a generic invalid-request code, such as Anthropic invalid_request_error or Bedrock ValidationException, is classified as context overflow when its message reports an oversized prompt, and as transient when it reports temporary provider capacity such as Azure peak-load rejection. server_busy, "servers are currently busy", and "model is at capacity" errors are transient and retryable. Rate-limit and transient wording, such as "rate limit", "throttling", or an upstream "context deadline exceeded", is never read as overflow, and an HTTP 429 without a structured code is rate limited even when its text mentions tokens. Bedrock's X-Amzn-Errortype header supplies the provider code, so ThrottlingException is rate limited. IsContextOverflow applies the same rules to the diagnostics on a final message, including overflow already detected by the provider adapter.

The classifier unwraps *sigma.GenerationError, *sigma.Error, and *sigma.ProviderError. It preserves the ordinary Go inspection path, so callers can combine it with sentinel and typed-error checks:

if errors.Is(err, sigma.ErrContextOverflow) {
	// Same signal as ErrorClassContextOverflow.
}

var providerErr *sigma.ProviderError
if errors.As(err, &providerErr) {
	log.Println(providerErr.Provider, providerErr.StatusCode, providerErr.ProviderCode)
}

Stream Errors

Generic stream wrappers preserve authentication classification for ErrCredentialUnavailable and transient classification for retryable network causes such as connection resets and unexpected EOF. Other stream failures are classified from their message, so HTTP/2 stream resets and GOAWAY closures while reading a response body are transient. RoutePolicy.Fallback therefore advises retrying the same model for transient failures; authentication failures retain fallback-or-abort advice. Classification adds no automatic replay. Typed provider errors, context overflow, cancellation, invalid options, and debug hook errors retain their existing precedence, error chains, and redaction.

Stream terminal errors are wrapped in *sigma.GenerationError, which preserves the final assistant message:

final, err := sigma.Collect(ctx, stream)
if err != nil {
	var generationErr *sigma.GenerationError
	if errors.As(err, &generationErr) {
		final, _ = generationErr.FinalMessage()
	}
}

For non-streaming callers, Client.Complete and Client.CompleteText return the same errors that Collect returns.

Cancellation

Use context.Context for cancellation and deadlines:

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

final, err := client.Complete(ctx, model, req)
if errors.Is(err, sigma.ErrAborted) || errors.Is(err, context.DeadlineExceeded) {
	_ = final
}

Text providers should preserve any partial content emitted before cancellation. Canceled streams end with StopReasonAborted when the provider records a final assistant message. Image providers may return an aborted stop reason without partial content.

See Cancellation for persistence guidance around aborted assistant messages.

Missing OpenAI Chat Completions finish_reason and image generation/edit completion events classify as ErrorClassTransient with retryable advice. Available output and usage remain attached to the failed result. This advice supports caller recovery decisions; it does not automatically replay a request after streaming starts. The opt-in Chat Completions [DONE] compatibility mode continues accepting an explicit [DONE] without finish_reason.

Retries And Timeouts

HTTP providers share sigma's retry policy:

  • no retries by default (DefaultMaxRetries is 0)
  • optional request timeout with sigma.WithTimeout; when it elapses during a text stream, the stream ends with StopReasonError and a transient, retryable error that matches context.DeadlineExceeded, while caller cancellation and caller deadlines still end as StopReasonAborted
  • retries only for transient network errors and HTTP 408, 409, 429, and 5xx, unless the provider's x-should-retry header says otherwise
  • provider Retry-After and Retry-After-Ms, including fractional values, are honored when they do not exceed WithMaxRetryDelay; a zero maximum retries without backoff and fails any response that asks to wait
  • streaming responses are not retried after the response body has been handed to the stream parser
final, err := client.Complete(
	ctx,
	model,
	req,
	sigma.WithTimeout(30*time.Second),
	sigma.WithMaxRetries(2),
	sigma.WithMaxRetryDelay(5*time.Second),
)

Tool Validation

sigma.ValidateToolCall returns *sigma.ToolValidationError for schema or argument failures. It matches sigma.ErrToolValidation, and sigma.ToolErrorMessage converts it to a safe tool-result string for retrying a model turn.

Credential Errors

Credential lookup failures return *sigma.CredentialUnavailableError and match sigma.ErrCredentialUnavailable. The error lists redacted sources checked by the credential chain.