Error Handling

GoAI returns two error types from generation calls. Use errors.As to inspect them.

APIError

Returned for HTTP errors from the provider (rate limits, auth failures, server errors).

type APIError struct {
    Message         string
    StatusCode      int
    IsRetryable     bool
    ResponseBody    string
    ResponseHeaders map[string]string
}

result, err := goai.GenerateText(ctx, model, goai.WithPrompt("Hello"))
if err != nil {
    var apiErr *goai.APIError
    if errors.As(err, &apiErr) {
        fmt.Printf("HTTP %d: %s (retryable: %v)\n",
            apiErr.StatusCode, apiErr.Message, apiErr.IsRetryable)
    }
}

ContextOverflowError

Returned when the prompt exceeds the model's context window. GoAI detects this from provider error messages across all supported providers.

type ContextOverflowError struct {
    Message      string
    ResponseBody string
}

var overflow *goai.ContextOverflowError
if errors.As(err, &overflow) {
    // Truncate messages and retry, or switch to a model with a larger context.
    fmt.Println("Context overflow:", overflow.Message)
}

IsOverflow

IsOverflow checks an arbitrary error message string against known overflow patterns from all major providers. Useful if you handle raw HTTP responses yourself.

if goai.IsOverflow(someErrorMessage) {
    // Handle context overflow
}

Retry Behavior

GoAI automatically retries on transient errors. Control this with WithMaxRetries (default: 2).

result, err := goai.GenerateText(ctx, model,
    goai.WithPrompt("Hello"),
    goai.WithMaxRetries(3),
)

Which errors are retried

An error is retried only if APIError.IsRetryable is true. This includes:

• HTTP 429 (Too Many Requests)
• HTTP 503 (Service Unavailable)
• HTTP 5xx (Server Errors)
• HTTP 404 from OpenAI (intermittent model availability)

These errors are never retried:

• HTTP 400 (Bad Request)
• HTTP 401 (Unauthorized)
• HTTP 403 (Forbidden)
• ContextOverflowError
• Any non-API error (network timeout, context cancellation)

Backoff strategy

Retries use exponential backoff with jitter:

• Base delay: 1s, 2s, 4s, 8s, ... capped at 30s
• Jitter: 0.5x to 1.5x of the base delay
• Respects context cancellation during the wait

Disabling retries

goai.WithMaxRetries(0) // No retries, fail on first error