fix(api): map billing errors to actionable codes instead of internal

[whoAbhishekSah]

What

Adds one shared fallback, mapBillingError, and uses it in place of the ~87 bare connect.CodeInternal wraps across the billing handlers:

error	code	message
billing.ErrProviderResourceMissing	failed_precondition	billing account is no longer linked to the payment provider
billing.ErrPaymentFailed	failed_precondition	payment failed: <Stripe's message>
billing.ErrProviderUnavailable	unavailable	billing provider is unavailable, retry later
subscription.ErrSubscriptionOnProviderNotFound	failed_precondition	subscription no longer exists on the billing provider
subscription.ErrPhaseIsUpdating	failed_precondition	phase is in the middle of a change, please try again later
customer.ErrExistingAccountWithPendingDues	failed_precondition	existing account with pending dues found
anything else	internal	unchanged

The existing specific mappings in the handlers (errors.Is ladders for not-found, invalid-argument, and so on) are untouched; only the final fallback changes. The rewrite was done with gofmt -r, so every call keeps its context string.

Why

internal should mean "a bug in Frontier". Today it also covers ordinary account states the caller can fix — the clearest case being GetUpcomingInvoice returning internal forever when the org's Stripe customer was deleted (#1835). With this change the caller learns whose move it is: fix the account, retry later, or report a bug.

Fixes #1836. Stack: translator (#1849) → services (#1850) → this PR.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
frontier	Ready	Preview	Aug 5, 2026 11:41am

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 31cd9698-a92b-4ede-98ed-8659b52cb96a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coveralls]

Coverage Report for CI Build 30980108222

Coverage increased (+0.04%) to 47.604%

Details

• Coverage increased (+0.04%) from the base build.
• Patch coverage: 61 uncovered changes across 10 files (65 of 126 lines covered, 51.59%).
• No coverage regressions found.

Uncovered Changes

File	Changed	Covered	%
internal/api/v1beta1connect/billing_customer.go	22	1	4.55%
internal/api/v1beta1connect/billing_product.go	20	9	45.0%
internal/api/v1beta1connect/billing_subscription.go	7	0	0.0%
internal/api/v1beta1connect/billing_invoice.go	10	4	40.0%
internal/api/v1beta1connect/billing_usage.go	9	3	33.33%
internal/api/v1beta1connect/billing_checkout.go	11	6	54.55%
billing/checkout/service.go	2	0	0.0%
internal/api/v1beta1connect/billing_check.go	5	4	80.0%
internal/api/v1beta1connect/billing_errors.go	32	31	96.88%
internal/api/v1beta1connect/billing_plan.go	7	6	85.71%
Total (11 files)	126	65	51.59%

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	39413
Covered Lines:	18762
Line Coverage:	47.6%
Coverage Strength:	15.4 hits per line

---

💛 - Coveralls

[rohilsurana]

Reviewed with the rest of the stack. The mapping table is sensible, the mechanical rewrite kept every context string (spot checked), and the test table is thorough: redaction shapes, test-mode ids, and caller-supplied coupon codes are all covered. Promoting already subscribed to the plan to a sentinel with already_exists is a nice touch, and the UpdateProduct refactor keeps the ErrInvalidDetail to invalid_argument path intact.

One real concern about what ends up in server logs, and two smaller points, all inline.

Also checked BillingWebhookCallback: it now answers the webhook sender with 412/503 instead of 500 for provider problems. Stripe retries on any non-2xx, so retry behavior does not change.

[rohilsurana]

LGTM overall. Please look at the logging comment on mapBillingError before merge.