feat(errors): translate infra-api blocked-team 403s into friendly text (#325)

Pairs with the infra-api, which returns 403 "team is blocked[:
<reason>]" for endpoints a blocked team can't access. The dashboard
previously collapsed every 403 into "You are not authorized to access
this resource", hiding the actual reason from the user.

This recognizes the wire format inside the central error adapter and
translates it into the existing user-facing messages.

Author: drankou

src/core/modules/teams/constants.ts

@@ -1,6 +1,15 @@
+/**
+ * Known reasons used by infra/billing services when blocking a team.
+ *
+ * These values are matched as case-insensitive substrings against the
+ * `blocked_reason` column (see `teams.blocked_reason`) and against the
+ * `team is blocked: <reason>` wire format returned by infra-api.
+ *
+ */
 const TEAM_BLOCKED_REASONS = {
   missingPayment: 'missing payment method',
   verification: 'verification required',
+  billingLimit: 'billing limit',
 } as const
 
 export { TEAM_BLOCKED_REASONS }

src/core/shared/errors.ts

@@ -1,5 +1,14 @@
+import { getBlockedReasonText } from '@/features/dashboard/team-blocked/team-blocked-message'
 import type { RepoError, RepoErrorCode } from './result'
 
+/**
+ * Wire-format prefix used by infra-api for 403 responses caused by a
+ * blocked team. The dashboard pattern-matches this prefix to translate
+ * the response into a friendly, user-facing message.
+ *
+ */
+export const TEAM_BLOCKED_MESSAGE_PREFIX = 'team is blocked'
+
 export const PUBLIC_ERROR_MESSAGE_UNAUTHORIZED = 'Unauthorized'
 export const PUBLIC_ERROR_MESSAGE_FORBIDDEN =
   'You are not authorized to access this resource'
@@ -45,6 +54,27 @@ export const ApiError = (message: string) => new E2BError('API_ERROR', message)
 export const UnknownError = (message?: string) =>
   new E2BError('UNKNOWN', message ?? PUBLIC_ERROR_MESSAGE_INTERNAL)
 
+export function isTeamBlockedError(input: {
+  status?: number
+  message?: string | null
+}): boolean {
+  if (input.status !== 403 || !input.message) return false
+  return input.message.toLowerCase().startsWith(TEAM_BLOCKED_MESSAGE_PREFIX)
+}
+
+export function extractBlockedReason(
+  message: string | null | undefined
+): string | null {
+  if (!message) return null
+  const lower = message.toLowerCase()
+  if (!lower.startsWith(TEAM_BLOCKED_MESSAGE_PREFIX)) return null
+  const rest = message
+    .slice(TEAM_BLOCKED_MESSAGE_PREFIX.length)
+    .replace(/^[:\s]+/, '')
+    .trim()
+  return rest || null
+}
+
 export function createRepoError(input: {
   code: RepoErrorCode
   status: number
@@ -62,8 +92,13 @@ export function createRepoError(input: {
 export function getPublicErrorMessage(input: {
   code?: RepoErrorCode | string
   status?: number
+  message?: string
 }): string {
-  const { code, status } = input
+  const { code, status, message } = input
+
+  if (isTeamBlockedError({ status, message })) {
+    return getBlockedReasonText(extractBlockedReason(message))
+  }
 
   if (code === 'unauthorized' || status === 401)
     return PUBLIC_ERROR_MESSAGE_UNAUTHORIZED
@@ -86,7 +121,11 @@ export function getPublicRepoErrorMessage(error: RepoError): string {
     case 'conflict':
       return error.message
     default:
-      return getPublicErrorMessage({ code: error.code, status: error.status })
+      return getPublicErrorMessage({
+        code: error.code,
+        status: error.status,
+        message: error.message,
+      })
   }
 }
 

src/features/dashboard/team-blocked/team-blocked-message.ts

@@ -7,38 +7,55 @@ export interface BlockedMessage {
   href: string | null
 }
 
+export function getBlockedReasonText(blockedReason: string | null): string {
+  const reason = blockedReason?.toLowerCase() ?? ''
+
+  if (reason.includes(TEAM_BLOCKED_REASONS.billingLimit)) {
+    return 'Billing limit reached.'
+  }
+  if (reason.includes(TEAM_BLOCKED_REASONS.missingPayment)) {
+    return 'Missing payment method.'
+  }
+  if (reason.includes(TEAM_BLOCKED_REASONS.verification)) {
+    return 'Verification required.'
+  }
+
+  return blockedReason ?? 'Team suspended.'
+}
+
 export function getBlockedMessage(
   slug: string,
   blockedReason: string | null
 ): BlockedMessage {
   const reason = blockedReason?.toLowerCase() ?? ''
+  const text = getBlockedReasonText(blockedReason)
 
-  if (reason.includes('billing limit')) {
+  if (reason.includes(TEAM_BLOCKED_REASONS.billingLimit)) {
     return {
-      text: 'Billing limit reached.',
+      text,
       cta: 'Update limit.',
       href: PROTECTED_URLS.LIMITS(slug),
     }
   }
 
   if (reason.includes(TEAM_BLOCKED_REASONS.missingPayment)) {
     return {
-      text: 'Missing payment method.',
+      text,
       cta: 'Add payment method.',
       href: null,
     }
   }
 
   if (reason.includes(TEAM_BLOCKED_REASONS.verification)) {
     return {
-      text: 'Verification required.',
+      text,
       cta: 'Complete verification.',
       href: null,
     }
   }
 
   return {
-    text: blockedReason ?? 'Team suspended.',
+    text,
     cta: null,
     href: null,
   }

tests/unit/team-blocked-error-handling.test.ts

@@ -0,0 +1,204 @@
+import { describe, expect, it } from 'vitest'
+import {
+  extractBlockedReason,
+  getPublicErrorMessage,
+  getPublicRepoErrorMessage,
+  isTeamBlockedError,
+  PUBLIC_ERROR_MESSAGE_FORBIDDEN,
+  PUBLIC_ERROR_MESSAGE_INTERNAL,
+} from '@/core/shared/errors'
+
+describe('isTeamBlockedError', () => {
+  it('matches 403 with the bare "team is blocked" prefix', () => {
+    expect(
+      isTeamBlockedError({ status: 403, message: 'team is blocked' })
+    ).toBe(true)
+  })
+
+  it('matches 403 with a reason suffix', () => {
+    expect(
+      isTeamBlockedError({
+        status: 403,
+        message: 'team is blocked: billing limit',
+      })
+    ).toBe(true)
+  })
+
+  it('is case-insensitive on the prefix', () => {
+    expect(
+      isTeamBlockedError({
+        status: 403,
+        message: 'Team Is Blocked: Verification Required',
+      })
+    ).toBe(true)
+  })
+
+  it('rejects non-403 statuses', () => {
+    expect(
+      isTeamBlockedError({ status: 401, message: 'team is blocked' })
+    ).toBe(false)
+    expect(
+      isTeamBlockedError({ status: 500, message: 'team is blocked' })
+    ).toBe(false)
+  })
+
+  it('rejects 403 responses without the prefix', () => {
+    expect(isTeamBlockedError({ status: 403, message: 'team is banned' })).toBe(
+      false
+    )
+    expect(isTeamBlockedError({ status: 403, message: 'forbidden' })).toBe(
+      false
+    )
+  })
+
+  it('rejects missing message', () => {
+    expect(isTeamBlockedError({ status: 403, message: null })).toBe(false)
+    expect(isTeamBlockedError({ status: 403, message: undefined })).toBe(false)
+  })
+})
+
+describe('extractBlockedReason', () => {
+  it('extracts a simple reason', () => {
+    expect(extractBlockedReason('team is blocked: billing limit')).toBe(
+      'billing limit'
+    )
+    expect(extractBlockedReason('team is blocked: verification required')).toBe(
+      'verification required'
+    )
+  })
+
+  it('returns null for the bare prefix', () => {
+    expect(extractBlockedReason('team is blocked')).toBeNull()
+  })
+
+  it('returns null for non-blocked messages', () => {
+    expect(extractBlockedReason('forbidden')).toBeNull()
+    expect(extractBlockedReason('team is banned')).toBeNull()
+  })
+
+  it('trims extra whitespace around the reason', () => {
+    expect(
+      extractBlockedReason('team is blocked:  verification required ')
+    ).toBe('verification required')
+  })
+
+  it('returns null on null/undefined/empty input', () => {
+    expect(extractBlockedReason(null)).toBeNull()
+    expect(extractBlockedReason(undefined)).toBeNull()
+    expect(extractBlockedReason('')).toBeNull()
+  })
+})
+
+describe('getPublicErrorMessage with team-blocked translation', () => {
+  it('translates billing-limit blocked messages', () => {
+    expect(
+      getPublicErrorMessage({
+        status: 403,
+        message: 'team is blocked: billing limit',
+      })
+    ).toBe('Billing limit reached.')
+  })
+
+  it('translates verification-required blocked messages', () => {
+    expect(
+      getPublicErrorMessage({
+        status: 403,
+        message: 'team is blocked: verification required',
+      })
+    ).toBe('Verification required.')
+  })
+
+  it('translates missing-payment-method blocked messages', () => {
+    expect(
+      getPublicErrorMessage({
+        status: 403,
+        message: 'team is blocked: missing payment method',
+      })
+    ).toBe('Missing payment method.')
+  })
+
+  it('returns the raw reason for unrecognized blocked reasons', () => {
+    expect(
+      getPublicErrorMessage({
+        status: 403,
+        message: 'team is blocked: blocked by support',
+      })
+    ).toBe('blocked by support')
+  })
+
+  it('returns generic "Team suspended." for the bare prefix', () => {
+    expect(
+      getPublicErrorMessage({ status: 403, message: 'team is blocked' })
+    ).toBe('Team suspended.')
+  })
+
+  it('falls through to generic forbidden when message is missing', () => {
+    expect(getPublicErrorMessage({ status: 403 })).toBe(
+      PUBLIC_ERROR_MESSAGE_FORBIDDEN
+    )
+    expect(getPublicErrorMessage({ code: 'forbidden' })).toBe(
+      PUBLIC_ERROR_MESSAGE_FORBIDDEN
+    )
+  })
+
+  it('falls through to generic forbidden for non-blocked 403 messages', () => {
+    expect(
+      getPublicErrorMessage({ status: 403, message: 'something else' })
+    ).toBe(PUBLIC_ERROR_MESSAGE_FORBIDDEN)
+  })
+
+  it('does not translate when status is not 403', () => {
+    expect(
+      getPublicErrorMessage({
+        status: 500,
+        message: 'team is blocked: billing limit',
+      })
+    ).toBe(PUBLIC_ERROR_MESSAGE_INTERNAL)
+  })
+})
+
+describe('getPublicRepoErrorMessage', () => {
+  it('forwards message so team-blocked translation fires', () => {
+    expect(
+      getPublicRepoErrorMessage({
+        code: 'forbidden',
+        status: 403,
+        message: 'team is blocked: billing limit',
+      })
+    ).toBe('Billing limit reached.')
+  })
+
+  it('obfuscates non-blocked 403s', () => {
+    expect(
+      getPublicRepoErrorMessage({
+        code: 'forbidden',
+        status: 403,
+        message: 'unauthorized for this endpoint',
+      })
+    ).toBe(PUBLIC_ERROR_MESSAGE_FORBIDDEN)
+  })
+
+  it('returns raw message for not_found / validation / conflict', () => {
+    expect(
+      getPublicRepoErrorMessage({
+        code: 'not_found',
+        status: 404,
+        message: 'team not found',
+      })
+    ).toBe('team not found')
+    expect(
+      getPublicRepoErrorMessage({
+        code: 'validation',
+        status: 400,
+        message: 'invalid input: foo',
+      })
+    ).toBe('invalid input: foo')
+    expect(
+      getPublicRepoErrorMessage({
+        code: 'conflict',
+        status: 409,
+        message: 'team slug taken',
+      })
+    ).toBe('team slug taken')
+  })
+})

tests/unit/team-blocked-message.test.ts

@@ -1,5 +1,8 @@
 import { describe, expect, it } from 'vitest'
-import { getBlockedMessage } from '@/features/dashboard/team-blocked/team-blocked-message'
+import {
+  getBlockedMessage,
+  getBlockedReasonText,
+} from '@/features/dashboard/team-blocked/team-blocked-message'
 
 describe('getBlockedMessage', () => {
   it('links billing limit blocks to limits', () => {
@@ -34,3 +37,34 @@ describe('getBlockedMessage', () => {
     })
   })
 })
+
+describe('getBlockedReasonText', () => {
+  it('returns the friendly text for billing limit', () => {
+    expect(getBlockedReasonText('billing limit')).toBe('Billing limit reached.')
+    expect(getBlockedReasonText('Billing limit reached')).toBe(
+      'Billing limit reached.'
+    )
+  })
+
+  it('returns the friendly text for missing payment method', () => {
+    expect(getBlockedReasonText('missing payment method')).toBe(
+      'Missing payment method.'
+    )
+  })
+
+  it('returns the friendly text for verification required', () => {
+    expect(getBlockedReasonText('verification required')).toBe(
+      'Verification required.'
+    )
+  })
+
+  it('returns the raw reason for support-set messages', () => {
+    expect(getBlockedReasonText('blocked by support')).toBe(
+      'blocked by support'
+    )
+  })
+
+  it('returns a generic fallback for null reason', () => {
+    expect(getBlockedReasonText(null)).toBe('Team suspended.')
+  })
+})