fix(api): keep provider message and map more billing errors

- pass the provider's message through for resource-missing errors so a
  missing coupon or payment method isn't reported as an unlinked account
- map customer not-found to not_found instead of internal
- name the already-subscribed checkout error and map it to already_exists
- map product and feature not-found to not_found

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: whoAbhishekSah

billing/checkout/checkout.go

@@ -20,11 +20,12 @@ func (s State) String() string {
 }
 
 var (
-	ErrNotFound      = errors.New("checkout not found")
-	ErrInvalidUUID   = errors.New("invalid syntax of uuid")
-	ErrInvalidID     = errors.New("invalid checkout id")
-	ErrInvalidDetail = errors.New("invalid checkout detail")
-	ErrKycCompleted  = errors.New("organization kyc completed")
+	ErrNotFound          = errors.New("checkout not found")
+	ErrInvalidUUID       = errors.New("invalid syntax of uuid")
+	ErrInvalidID         = errors.New("invalid checkout id")
+	ErrInvalidDetail     = errors.New("invalid checkout detail")
+	ErrKycCompleted      = errors.New("organization kyc completed")
+	ErrAlreadySubscribed = errors.New("already subscribed to the plan")
 )
 
 type Checkout struct {

billing/checkout/service.go

@@ -248,7 +248,7 @@ func (s *Service) Create(ctx context.Context, ch Checkout) (Checkout, error) {
 		if subID, err := s.checkIfAlreadySubscribed(ctx, ch); err != nil {
 			return Checkout{}, err
 		} else if subID != "" {
-			return Checkout{}, fmt.Errorf("already subscribed to the plan")
+			return Checkout{}, ErrAlreadySubscribed
 		}
 
 		// create subscription items
@@ -894,7 +894,7 @@ func (s *Service) Apply(ctx context.Context, ch Checkout) (*subscription.Subscri
 		if subID, err := s.checkIfAlreadySubscribed(ctx, ch); err != nil {
 			return nil, nil, err
 		} else if subID != "" {
-			return nil, nil, fmt.Errorf("already subscribed to the plan")
+			return nil, nil, ErrAlreadySubscribed
 		}
 
 		if err := s.cancelTrialingSubscription(ctx, ch.CustomerID, ch.PlanID); err != nil {

internal/api/v1beta1connect/billing_errors.go

@@ -5,8 +5,10 @@ import (
 
 	"connectrpc.com/connect"
 
+	"github.com/raystack/frontier/billing/checkout"
 	"github.com/raystack/frontier/billing/customer"
 	billingerrors "github.com/raystack/frontier/billing/errors"
+	"github.com/raystack/frontier/billing/product"
 	"github.com/raystack/frontier/billing/subscription"
 )
 
@@ -16,6 +18,10 @@ import (
 func mapBillingError(err error) *connect.Error {
 	switch {
 	case errors.Is(err, billingerrors.ErrProviderResourceMissing):
+		var providerErr *billingerrors.ProviderError
+		if errors.As(err, &providerErr) {
+			return connect.NewError(connect.CodeFailedPrecondition, providerErr)
+		}
 		return connect.NewError(connect.CodeFailedPrecondition, ErrBillingProviderResourceMissing)
 	case errors.Is(err, billingerrors.ErrPaymentFailed):
 		var providerErr *billingerrors.ProviderError
@@ -31,6 +37,14 @@ func mapBillingError(err error) *connect.Error {
 		return connect.NewError(connect.CodeFailedPrecondition, subscription.ErrPhaseIsUpdating)
 	case errors.Is(err, customer.ErrExistingAccountWithPendingDues):
 		return connect.NewError(connect.CodeFailedPrecondition, customer.ErrExistingAccountWithPendingDues)
+	case errors.Is(err, customer.ErrNotFound):
+		return connect.NewError(connect.CodeNotFound, ErrCustomerNotFound)
+	case errors.Is(err, checkout.ErrAlreadySubscribed):
+		return connect.NewError(connect.CodeAlreadyExists, checkout.ErrAlreadySubscribed)
+	case errors.Is(err, product.ErrProductNotFound):
+		return connect.NewError(connect.CodeNotFound, product.ErrProductNotFound)
+	case errors.Is(err, product.ErrFeatureNotFound):
+		return connect.NewError(connect.CodeNotFound, product.ErrFeatureNotFound)
 	default:
 		return connect.NewError(connect.CodeInternal, err)
 	}

internal/api/v1beta1connect/billing_errors_test.go

@@ -9,8 +9,10 @@ import (
 	"github.com/stretchr/testify/assert"
 	stripe "github.com/stripe/stripe-go/v79"
 
+	"github.com/raystack/frontier/billing/checkout"
 	"github.com/raystack/frontier/billing/customer"
 	billingerrors "github.com/raystack/frontier/billing/errors"
+	"github.com/raystack/frontier/billing/product"
 	"github.com/raystack/frontier/billing/subscription"
 )
 
@@ -34,9 +36,15 @@ func TestMapBillingError(t *testing.T) {
 		wantMsg  string
 	}{
 		{
-			name:     "provider resource missing",
+			name:     "provider resource missing keeps provider message",
 			err:      fmt.Errorf("GetUpcomingInvoice: org_id=abc: %w", deadCustomer),
 			wantCode: connect.CodeFailedPrecondition,
+			wantMsg:  "record no longer exists on the billing provider: No such customer: 'cus_123'",
+		},
+		{
+			name:     "provider resource missing without provider error",
+			err:      fmt.Errorf("GetUpcomingInvoice: %w", billingerrors.ErrProviderResourceMissing),
+			wantCode: connect.CodeFailedPrecondition,
 			wantMsg:  ErrBillingProviderResourceMissing.Error(),
 		},
 		{
@@ -69,6 +77,30 @@ func TestMapBillingError(t *testing.T) {
 			wantCode: connect.CodeFailedPrecondition,
 			wantMsg:  customer.ErrExistingAccountWithPendingDues.Error(),
 		},
+		{
+			name:     "customer not found",
+			err:      fmt.Errorf("CreateCheckout.GetBillingAccountFromOrgID: org_id=abc: %w", customer.ErrNotFound),
+			wantCode: connect.CodeNotFound,
+			wantMsg:  ErrCustomerNotFound.Error(),
+		},
+		{
+			name:     "already subscribed to the plan",
+			err:      fmt.Errorf("CreateCheckout.Create: %w", checkout.ErrAlreadySubscribed),
+			wantCode: connect.CodeAlreadyExists,
+			wantMsg:  checkout.ErrAlreadySubscribed.Error(),
+		},
+		{
+			name:     "product not found",
+			err:      fmt.Errorf("GetProduct.GetByID: product_id=abc: %w", product.ErrProductNotFound),
+			wantCode: connect.CodeNotFound,
+			wantMsg:  product.ErrProductNotFound.Error(),
+		},
+		{
+			name:     "feature not found",
+			err:      fmt.Errorf("CheckFeatureEntitlement: feature=abc: %w", product.ErrFeatureNotFound),
+			wantCode: connect.CodeNotFound,
+			wantMsg:  product.ErrFeatureNotFound.Error(),
+		},
 		{
 			name:     "unknown error stays internal",
 			err:      fmt.Errorf("GetBillingAccount: %w", errors.New("db down")),