feat: classify provider_disabled 503 as non-retryable (#25800)

Builds on top of https://github.com/coder/coder/pull/25794

Adds a new `provider_disabled` error classification in `chatd` with the
corresponding plumbing to classify it as non-retryable. Also adds a
story for how this particular error kind is displayed in the UI.

coderd/apidoc/docs.go

@@ -16498,7 +16498,8 @@ const docTemplate = `{
                 "auth",
                 "config",
                 "usage_limit",
-                "missing_key"
+                "missing_key",
+                "provider_disabled"
             ],
             "x-enum-varnames": [
                 "ChatErrorKindGeneric",
@@ -16509,7 +16510,8 @@ const docTemplate = `{
                 "ChatErrorKindAuth",
                 "ChatErrorKindConfig",
                 "ChatErrorKindUsageLimit",
-                "ChatErrorKindMissingKey"
+                "ChatErrorKindMissingKey",
+                "ChatErrorKindProviderDisabled"
             ]
         },
         "codersdk.ChatFileMetadata": {

coderd/apidoc/swagger.json

@@ -14848,7 +14848,8 @@
 				"auth",
 				"config",
 				"usage_limit",
-				"missing_key"
+				"missing_key",
+				"provider_disabled"
 			],
 			"x-enum-varnames": [
 				"ChatErrorKindGeneric",
@@ -14859,7 +14860,8 @@
 				"ChatErrorKindAuth",
 				"ChatErrorKindConfig",
 				"ChatErrorKindUsageLimit",
-				"ChatErrorKindMissingKey"
+				"ChatErrorKindMissingKey",
+				"ChatErrorKindProviderDisabled"
 			]
 		},
 		"codersdk.ChatFileMetadata": {

coderd/x/chatd/chaterror/classify.go

@@ -195,6 +195,7 @@ func Classify(err error) ClassifiedError {
 	}
 
 	retryableHTTP2StreamReset, hasHTTP2StreamReset := classifyHTTP2StreamReset(err)
+	providerDisabledMatch := containsAny(lower, providerDisabledPatterns...)
 	deadline := errors.Is(err, context.DeadlineExceeded) || strings.Contains(lower, "context deadline exceeded")
 	overloadedMatch := statusCode == 529 || containsAny(lower, overloadedPatterns...)
 	usageLimitMatch := containsAny(lower, usageLimitPatterns...)
@@ -221,6 +222,8 @@ func Classify(err error) ClassifiedError {
 	// over whatever HTTP status code the provider happened to use.
 	// Strong auth still stays above config because bad credentials are
 	// the root cause when both signals appear.
+	// Provider-disabled must precede timeout because disabled providers
+	// return 503, which matches the timeout rule.
 	rules := []struct {
 		match     bool
 		kind      codersdk.ChatErrorKind
@@ -251,6 +254,11 @@ func Classify(err error) ClassifiedError {
 			kind:      codersdk.ChatErrorKindRateLimit,
 			retryable: true,
 		},
+		{
+			match:     providerDisabledMatch,
+			kind:      codersdk.ChatErrorKindProviderDisabled,
+			retryable: false,
+		},
 		{
 			match:     timeoutMatch && !configMatch,
 			kind:      codersdk.ChatErrorKindTimeout,

coderd/x/chatd/chaterror/classify_test.go

@@ -2,6 +2,7 @@ package chaterror_test
 
 import (
 	"context"
+	"fmt"
 	"io"
 	"net/http"
 	"strings"
@@ -218,6 +219,85 @@ func TestClassify(t *testing.T) {
 				StatusCode: 0,
 			},
 		},
+		// The next cases model the error that fantasy produces
+		// when aibridge's disabledProviderHandler returns a 503
+		// plain-text sentinel. Fantasy sets Title from the HTTP
+		// status text and Message from the response body (including
+		// the trailing newline written by http.Error).
+		{
+			name: "ProviderDisabled503ClassifiesAsProviderDisabled",
+			err: &fantasy.ProviderError{
+				Title:      fantasy.ErrorTitleForStatusCode(http.StatusServiceUnavailable),
+				Message:    fmt.Sprintf("%s: AI provider %q is disabled\n", codersdk.ChatErrorKindProviderDisabled, "openai"),
+				StatusCode: http.StatusServiceUnavailable,
+			},
+			want: chaterror.ClassifiedError{
+				Message:    "The OpenAI provider has been disabled. Contact your Coder administrator.",
+				Detail:     fmt.Sprintf("%s: AI provider %q is disabled", codersdk.ChatErrorKindProviderDisabled, "openai"),
+				Kind:       codersdk.ChatErrorKindProviderDisabled,
+				Provider:   "openai",
+				Retryable:  false,
+				StatusCode: 503,
+			},
+		},
+		{
+			name: "ProviderDisabled503UnknownProvider",
+			err: &fantasy.ProviderError{
+				Title:      fantasy.ErrorTitleForStatusCode(http.StatusServiceUnavailable),
+				Message:    fmt.Sprintf("%s: AI provider %q is disabled\n", codersdk.ChatErrorKindProviderDisabled, "mycustomprovider"),
+				StatusCode: http.StatusServiceUnavailable,
+			},
+			want: chaterror.ClassifiedError{
+				Message:    "The AI provider has been disabled. Contact your Coder administrator.",
+				Detail:     fmt.Sprintf("%s: AI provider %q is disabled", codersdk.ChatErrorKindProviderDisabled, "mycustomprovider"),
+				Kind:       codersdk.ChatErrorKindProviderDisabled,
+				Provider:   "",
+				Retryable:  false,
+				StatusCode: 503,
+			},
+		},
+		{
+			name: "ProviderDisabledPlainErrorString",
+			err:  xerrors.New(fmt.Sprintf("%s: AI provider %q is disabled", codersdk.ChatErrorKindProviderDisabled, "anthropic")),
+			want: chaterror.ClassifiedError{
+				Message:    "The Anthropic provider has been disabled. Contact your Coder administrator.",
+				Kind:       codersdk.ChatErrorKindProviderDisabled,
+				Provider:   "anthropic",
+				Retryable:  false,
+				StatusCode: 0,
+			},
+		},
+		{
+			name: "ProviderDisabledBeatsTimeout503",
+			err: &fantasy.ProviderError{
+				Title:      fantasy.ErrorTitleForStatusCode(http.StatusServiceUnavailable),
+				Message:    fmt.Sprintf("%s: AI provider %q is disabled\n", codersdk.ChatErrorKindProviderDisabled, "google"),
+				StatusCode: http.StatusServiceUnavailable,
+			},
+			want: chaterror.ClassifiedError{
+				Message:    "The Google provider has been disabled. Contact your Coder administrator.",
+				Detail:     fmt.Sprintf("%s: AI provider %q is disabled", codersdk.ChatErrorKindProviderDisabled, "google"),
+				Kind:       codersdk.ChatErrorKindProviderDisabled,
+				Provider:   "google",
+				Retryable:  false,
+				StatusCode: 503,
+			},
+		},
+		{
+			name: "Generic503StillClassifiesAsTimeout",
+			err: &fantasy.ProviderError{
+				Message:    "service unavailable",
+				StatusCode: 503,
+			},
+			want: chaterror.ClassifiedError{
+				Message:    "The AI provider is temporarily unavailable.",
+				Detail:     "service unavailable",
+				Kind:       codersdk.ChatErrorKindTimeout,
+				Provider:   "",
+				Retryable:  true,
+				StatusCode: 503,
+			},
+		},
 	}
 
 	for _, tt := range tests {
@@ -363,6 +443,7 @@ func TestClassify_PatternCoverage(t *testing.T) {
 		{name: "OperationInterruptedLiteral", err: "operation interrupted", wantKind: codersdk.ChatErrorKindGeneric, wantRetry: false},
 		{name: "Status408", err: "status 408", wantKind: codersdk.ChatErrorKindTimeout, wantRetry: true},
 		{name: "Status500", err: "status 500", wantKind: codersdk.ChatErrorKindGeneric, wantRetry: true},
+		{name: "ProviderDisabledLiteral", err: "provider_disabled", wantKind: codersdk.ChatErrorKindProviderDisabled, wantRetry: false},
 	}
 
 	for _, tt := range tests {

coderd/x/chatd/chaterror/message.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"strings"
 
+	stringutil "github.com/coder/coder/v2/coderd/util/strings"
 	"github.com/coder/coder/v2/codersdk"
 )
 
@@ -16,60 +17,58 @@ func terminalMessage(classified ClassifiedError) string {
 	subject := providerSubject(classified.Provider)
 	switch classified.Kind {
 	case codersdk.ChatErrorKindOverloaded:
-		return fmt.Sprintf("%s is temporarily overloaded.", subject)
+		return stringutil.Capitalize(fmt.Sprintf("%s is temporarily overloaded.", subject))
 
 	case codersdk.ChatErrorKindRateLimit:
-		return fmt.Sprintf("%s is rate limiting requests.", subject)
+		return stringutil.Capitalize(fmt.Sprintf("%s is rate limiting requests.", subject))
 
 	case codersdk.ChatErrorKindTimeout:
 		if !classified.Retryable && classified.StatusCode == 0 {
 			return "The request timed out before it completed."
 		}
-		return fmt.Sprintf("%s is temporarily unavailable.", subject)
+		return stringutil.Capitalize(fmt.Sprintf("%s is temporarily unavailable.", subject))
 
 	case codersdk.ChatErrorKindStartupTimeout:
-		return fmt.Sprintf(
+		return stringutil.Capitalize(fmt.Sprintf(
 			"%s did not start responding in time.", subject,
-		)
+		))
 
 	case codersdk.ChatErrorKindUsageLimit:
-		displayName := providerDisplayName(classified.Provider)
-		if displayName == "" {
-			displayName = "the AI provider"
-		}
-		return fmt.Sprintf(
+		return stringutil.Capitalize(fmt.Sprintf(
 			"The usage quota for %s has been exceeded."+
 				" Check the billing and quota settings for the provider account.",
-			displayName,
-		)
+			subject,
+		))
 
 	case codersdk.ChatErrorKindAuth:
-		displayName := providerDisplayName(classified.Provider)
-		if displayName == "" {
-			displayName = "the AI provider"
-		}
 		return fmt.Sprintf(
 			"Authentication with %s failed."+
 				" Check the API key and permissions.",
-			displayName,
+			subject,
 		)
 
 	case codersdk.ChatErrorKindConfig:
-		return fmt.Sprintf(
+		return stringutil.Capitalize(fmt.Sprintf(
 			"%s rejected the model configuration."+
 				" Check the selected model and provider settings.",
 			subject,
-		)
+		))
 
 	case codersdk.ChatErrorKindMissingKey:
 		return "This conversation was started with an API key that is no longer available." +
 			" Send your message again to continue."
-
+	case codersdk.ChatErrorKindProviderDisabled:
+		displayName := providerDisplayName(classified.Provider)
+		return fmt.Sprintf(
+			"The %s provider has been disabled."+
+				" Contact your Coder administrator.",
+			displayName,
+		)
 	default:
 		if !classified.Retryable && classified.StatusCode == 0 {
 			return "The chat request failed unexpectedly."
 		}
-		return fmt.Sprintf("%s returned an unexpected error.", subject)
+		return stringutil.Capitalize(fmt.Sprintf("%s returned an unexpected error.", subject))
 	}
 }
 
@@ -85,41 +84,43 @@ func retryMessage(classified ClassifiedError) string {
 	subject := providerSubject(classified.Provider)
 	switch classified.Kind {
 	case codersdk.ChatErrorKindOverloaded:
-		return fmt.Sprintf("%s is temporarily overloaded.", subject)
+		return stringutil.Capitalize(fmt.Sprintf("%s is temporarily overloaded.", subject))
 	case codersdk.ChatErrorKindRateLimit:
-		return fmt.Sprintf("%s is rate limiting requests.", subject)
+		return stringutil.Capitalize(fmt.Sprintf("%s is rate limiting requests.", subject))
 	case codersdk.ChatErrorKindTimeout:
-		return fmt.Sprintf("%s is temporarily unavailable.", subject)
+		return stringutil.Capitalize(fmt.Sprintf("%s is temporarily unavailable.", subject))
 	case codersdk.ChatErrorKindStartupTimeout:
-		return fmt.Sprintf(
+		return stringutil.Capitalize(fmt.Sprintf(
 			"%s did not start responding in time.", subject,
-		)
+		))
 	case codersdk.ChatErrorKindAuth:
-		displayName := providerDisplayName(classified.Provider)
-		if displayName == "" {
-			displayName = "the AI provider"
-		}
 		return fmt.Sprintf(
-			"Authentication with %s failed.", displayName,
+			"Authentication with %s failed.", subject,
 		)
 	case codersdk.ChatErrorKindConfig:
-		return fmt.Sprintf(
+		return stringutil.Capitalize(fmt.Sprintf(
 			"%s rejected the model configuration.", subject,
-		)
+		))
 	case codersdk.ChatErrorKindMissingKey:
 		return "The API key for this conversation is no longer available."
-	default:
+	case codersdk.ChatErrorKindProviderDisabled:
+		displayName := providerDisplayName(classified.Provider)
 		return fmt.Sprintf(
-			"%s returned an unexpected error.", subject,
+			"The %s provider has been disabled by an administrator.",
+			displayName,
 		)
+	default:
+		return stringutil.Capitalize(fmt.Sprintf(
+			"%s returned an unexpected error.", subject,
+		))
 	}
 }
 
 func providerSubject(provider string) string {
-	if displayName := providerDisplayName(provider); displayName != "" {
+	if displayName := providerDisplayName(provider); displayName != "AI" && displayName != "" {
 		return displayName
 	}
-	return "The AI provider"
+	return "the AI provider"
 }
 
 func providerDisplayName(provider string) string {
@@ -141,7 +142,7 @@ func providerDisplayName(provider string) string {
 	case "vercel":
 		return "Vercel AI Gateway"
 	default:
-		return ""
+		return "AI"
 	}
 }
 

coderd/x/chatd/chaterror/signals.go

@@ -4,6 +4,8 @@ import (
 	"regexp"
 	"strconv"
 	"strings"
+
+	"github.com/coder/coder/v2/aibridge"
 )
 
 type providerHint struct {
@@ -83,6 +85,7 @@ var (
 	}
 	genericRetryablePatterns = []string{"server error", "internal server error"}
 	interruptedPatterns      = []string{"chat interrupted", "request interrupted", "operation interrupted"}
+	providerDisabledPatterns = []string{aibridge.ErrorCodeProviderDisabled}
 )
 
 func extractStatusCode(lower string) int {