refactor: use idiomatic Go error handling with errors.Is()

- Move error definitions to internal/api/errors.go
- Add classifyError() to detect error patterns from GraphQL responses
- Update conversation_service to wrap errors with sentinel types
- Update conversation_handler to use errors.Is() instead of string matching
- Remove IsNotFound/IsAlreadyExists helper functions (no longer needed)

The API layer now owns error classification, consumers use errors.Is().

Author: binarylogic

internal/api/api.go

@@ -1,48 +1,9 @@
 package api
 
 import (
-	"errors"
-	"strings"
-
 	"github.com/usetero/cli/internal/log"
 )
 
-// Sentinel errors for API responses.
-var (
-	// ErrNotFound indicates the requested resource does not exist.
-	ErrNotFound = errors.New("not found")
-
-	// ErrAlreadyExists indicates the resource already exists.
-	ErrAlreadyExists = errors.New("already exists")
-)
-
-// IsNotFound returns true if the error indicates a resource was not found.
-func IsNotFound(err error) bool {
-	if err == nil {
-		return false
-	}
-	if errors.Is(err, ErrNotFound) {
-		return true
-	}
-	// Check error message for common "not found" patterns from GraphQL
-	msg := strings.ToLower(err.Error())
-	return strings.Contains(msg, "not found") || strings.Contains(msg, "not_found")
-}
-
-// IsAlreadyExists returns true if the error indicates a resource already exists.
-func IsAlreadyExists(err error) bool {
-	if err == nil {
-		return false
-	}
-	if errors.Is(err, ErrAlreadyExists) {
-		return true
-	}
-	// Check error message for common "already exists" patterns from GraphQL
-	msg := strings.ToLower(err.Error())
-	return strings.Contains(msg, "already exists") || strings.Contains(msg, "already_exists") ||
-		strings.Contains(msg, "duplicate") || strings.Contains(msg, "conflict")
-}
-
 // API bundles all control plane API services.
 // It provides a single entry point for all API-related operations.
 type API struct {

internal/api/api_test.go

@@ -2,6 +2,8 @@ package api
 
 import (
 	"context"
+	"errors"
+	"fmt"
 
 	"github.com/google/uuid"
 	"github.com/usetero/cli/internal/log"
@@ -52,6 +54,9 @@ func (s *ConversationService) Create(ctx context.Context, id uuid.UUID, workspac
 	resp, err := s.client.CreateConversation(ctx, input)
 	if err != nil {
 		s.logger.Error("failed to create conversation", "error", err)
+		if classified := classifyError(err); classified != nil {
+			return nil, fmt.Errorf("create conversation %s: %w", id, classified)
+		}
 		return nil, err
 	}
 
@@ -76,6 +81,9 @@ func (s *ConversationService) Update(ctx context.Context, id, title string) (*Co
 	resp, err := s.client.UpdateConversation(ctx, id, input)
 	if err != nil {
 		s.logger.Error("failed to update conversation", "error", err, "id", id)
+		if classified := classifyError(err); classified != nil {
+			return nil, fmt.Errorf("update conversation %s: %w", id, classified)
+		}
 		return nil, err
 	}
 
@@ -89,12 +97,16 @@ func (s *ConversationService) Update(ctx context.Context, id, title string) (*Co
 }
 
 // Delete deletes a conversation.
+// Returns ErrNotFound (via errors.Is) if the conversation does not exist.
 func (s *ConversationService) Delete(ctx context.Context, id string) error {
 	s.logger.Debug("deleting conversation via API", "id", id)
 
 	_, err := s.client.DeleteConversation(ctx, id)
 	if err != nil {
 		s.logger.Error("failed to delete conversation", "error", err, "id", id)
+		if classified := classifyError(err); classified != nil {
+			return errors.Join(fmt.Errorf("delete conversation %s", id), classified)
+		}
 		return err
 	}
 

internal/api/conversation_service.go

@@ -0,0 +1,55 @@
+package api
+
+import (
+	"errors"
+	"strings"
+)
+
+// Sentinel errors for API responses.
+// Use errors.Is() to check for these error types.
+var (
+	// ErrNotFound indicates the requested resource does not exist.
+	ErrNotFound = errors.New("not found")
+
+	// ErrAlreadyExists indicates the resource already exists.
+	ErrAlreadyExists = errors.New("already exists")
+)
+
+// notFoundPatterns are substrings that indicate a "not found" error from the API.
+var notFoundPatterns = []string{
+	"not found",
+	"not_found",
+	"does not exist",
+}
+
+// alreadyExistsPatterns are substrings that indicate an "already exists" error from the API.
+var alreadyExistsPatterns = []string{
+	"already exists",
+	"already_exists",
+	"duplicate",
+	"conflict",
+}
+
+// classifyError examines an error message and returns a wrapped sentinel error
+// if the message matches known patterns. Returns nil if no pattern matches.
+func classifyError(err error) error {
+	if err == nil {
+		return nil
+	}
+
+	msg := strings.ToLower(err.Error())
+
+	for _, pattern := range notFoundPatterns {
+		if strings.Contains(msg, pattern) {
+			return ErrNotFound
+		}
+	}
+
+	for _, pattern := range alreadyExistsPatterns {
+		if strings.Contains(msg, pattern) {
+			return ErrAlreadyExists
+		}
+	}
+
+	return nil
+}

internal/api/errors.go

@@ -0,0 +1,116 @@
+package api
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+)
+
+func TestClassifyError(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		err  error
+		want error
+	}{
+		{
+			name: "nil error",
+			err:  nil,
+			want: nil,
+		},
+		{
+			name: "not found",
+			err:  errors.New("conversation not found"),
+			want: ErrNotFound,
+		},
+		{
+			name: "NOT_FOUND",
+			err:  errors.New("ERROR: NOT_FOUND"),
+			want: ErrNotFound,
+		},
+		{
+			name: "not_found",
+			err:  errors.New("resource_not_found"),
+			want: ErrNotFound,
+		},
+		{
+			name: "does not exist",
+			err:  errors.New("conversation does not exist"),
+			want: ErrNotFound,
+		},
+		{
+			name: "already exists",
+			err:  errors.New("conversation already exists"),
+			want: ErrAlreadyExists,
+		},
+		{
+			name: "ALREADY_EXISTS",
+			err:  errors.New("ERROR: ALREADY_EXISTS"),
+			want: ErrAlreadyExists,
+		},
+		{
+			name: "duplicate",
+			err:  errors.New("duplicate key violation"),
+			want: ErrAlreadyExists,
+		},
+		{
+			name: "conflict",
+			err:  errors.New("conflict: resource exists"),
+			want: ErrAlreadyExists,
+		},
+		{
+			name: "unrelated error",
+			err:  errors.New("network timeout"),
+			want: nil,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			got := classifyError(tt.err)
+			// classifyError returns sentinel errors directly (ErrNotFound, ErrAlreadyExists, or nil)
+			// so direct comparison is correct here
+			if (got == nil) != (tt.want == nil) || (got != nil && tt.want != nil && !errors.Is(got, tt.want)) {
+				t.Errorf("classifyError() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestClassifiedErrorsWorkWithErrorsIs(t *testing.T) {
+	t.Parallel()
+
+	t.Run("wrapped ErrNotFound", func(t *testing.T) {
+		t.Parallel()
+		original := errors.New("conversation not found")
+		classified := classifyError(original)
+		wrapped := fmt.Errorf("delete conversation abc: %w", classified)
+
+		if !errors.Is(wrapped, ErrNotFound) {
+			t.Error("errors.Is(wrapped, ErrNotFound) = false, want true")
+		}
+	})
+
+	t.Run("wrapped ErrAlreadyExists", func(t *testing.T) {
+		t.Parallel()
+		original := errors.New("conversation already exists")
+		classified := classifyError(original)
+		wrapped := fmt.Errorf("create conversation abc: %w", classified)
+
+		if !errors.Is(wrapped, ErrAlreadyExists) {
+			t.Error("errors.Is(wrapped, ErrAlreadyExists) = false, want true")
+		}
+	})
+
+	t.Run("errors.Join preserves both errors", func(t *testing.T) {
+		t.Parallel()
+		contextErr := fmt.Errorf("delete conversation %s", "abc")
+		joined := errors.Join(contextErr, ErrNotFound)
+
+		if !errors.Is(joined, ErrNotFound) {
+			t.Error("errors.Is(joined, ErrNotFound) = false, want true")
+		}
+	})
+}