Show better error message if someone uses freebuff in unsupported country

Author: jahooma

cli/src/utils/__tests__/error-handling.test.ts

@@ -2,7 +2,9 @@ import { describe, test, expect } from 'bun:test'
 
 import {
   isOutOfCreditsError,
+  isFreeModeUnavailableError,
   OUT_OF_CREDITS_MESSAGE,
+  FREE_MODE_UNAVAILABLE_MESSAGE,
   createErrorMessage,
 } from '../error-handling'
 
@@ -66,6 +68,50 @@ describe('error-handling', () => {
     })
   })
 
+  describe('isFreeModeUnavailableError', () => {
+    test('returns true for error with statusCode 403 and error free_mode_unavailable', () => {
+      const error = { statusCode: 403, error: 'free_mode_unavailable', message: 'Free mode is not available in your country.' }
+      expect(isFreeModeUnavailableError(error)).toBe(true)
+    })
+
+    test('returns false for 403 without error field', () => {
+      const error = { statusCode: 403, message: 'Forbidden' }
+      expect(isFreeModeUnavailableError(error)).toBe(false)
+    })
+
+    test('returns false for 403 with different error code', () => {
+      const error = { statusCode: 403, error: 'account_suspended', message: 'Suspended' }
+      expect(isFreeModeUnavailableError(error)).toBe(false)
+    })
+
+    test('returns false for non-403 status with free_mode_unavailable error', () => {
+      const error = { statusCode: 400, error: 'free_mode_unavailable', message: 'Bad request' }
+      expect(isFreeModeUnavailableError(error)).toBe(false)
+    })
+
+    test('returns false for null', () => {
+      expect(isFreeModeUnavailableError(null)).toBe(false)
+    })
+
+    test('returns false for undefined', () => {
+      expect(isFreeModeUnavailableError(undefined)).toBe(false)
+    })
+
+    test('returns false for plain Error object', () => {
+      expect(isFreeModeUnavailableError(new Error('Forbidden'))).toBe(false)
+    })
+  })
+
+  describe('FREE_MODE_UNAVAILABLE_MESSAGE', () => {
+    test('mentions free mode', () => {
+      expect(FREE_MODE_UNAVAILABLE_MESSAGE.toLowerCase()).toContain('free mode')
+    })
+
+    test('mentions paid plan', () => {
+      expect(FREE_MODE_UNAVAILABLE_MESSAGE.toLowerCase()).toContain('paid plan')
+    })
+  })
+
   describe('OUT_OF_CREDITS_MESSAGE', () => {
     test('contains usage URL', () => {
       expect(OUT_OF_CREDITS_MESSAGE).toContain('/usage')

sdk/src/__tests__/run-cancellation.test.ts

@@ -184,6 +184,121 @@ describe('Run Cancellation Handling', () => {
     expect(messageHistory.length).toBe(3)
   })
 
+  it('extracts error code and message from AI SDK responseBody on 403', async () => {
+    spyOn(databaseModule, 'getUserInfoFromApiKey').mockResolvedValue({
+      id: 'user-123',
+      email: 'test@example.com',
+      discord_id: null,
+      referral_code: null,
+      stripe_customer_id: null,
+      banned: false,
+    })
+    spyOn(databaseModule, 'fetchAgentFromDatabase').mockResolvedValue(null)
+    spyOn(databaseModule, 'startAgentRun').mockResolvedValue('run-1')
+    spyOn(databaseModule, 'finishAgentRun').mockResolvedValue(undefined)
+    spyOn(databaseModule, 'addAgentStep').mockResolvedValue('step-1')
+
+    // Simulate AI SDK's AI_APICallError with responseBody (what the server returns for free_mode_unavailable)
+    const apiError = new Error('Forbidden') as Error & { statusCode: number; responseBody: string }
+    apiError.statusCode = 403
+    apiError.responseBody = JSON.stringify({
+      error: 'free_mode_unavailable',
+      message: 'Free mode is not available in your country.',
+    })
+
+    spyOn(mainPromptModule, 'callMainPrompt').mockRejectedValue(apiError)
+
+    const client = new CodebuffClient({
+      apiKey: 'test-key',
+    })
+
+    const result = await client.run({
+      agent: 'base2',
+      prompt: 'hello',
+    })
+
+    expect(result.output.type).toBe('error')
+    const output = result.output as { type: 'error'; message: string; statusCode?: number; error?: string }
+    // Should use the message from the response body, not the generic "Forbidden"
+    expect(output.message).toBe('Free mode is not available in your country.')
+    expect(output.statusCode).toBe(403)
+    // Should propagate the error code so isFreeModeUnavailableError can match
+    expect(output.error).toBe('free_mode_unavailable')
+  })
+
+  it('extracts error code from responseBody for account_suspended 403', async () => {
+    spyOn(databaseModule, 'getUserInfoFromApiKey').mockResolvedValue({
+      id: 'user-123',
+      email: 'test@example.com',
+      discord_id: null,
+      referral_code: null,
+      stripe_customer_id: null,
+      banned: false,
+    })
+    spyOn(databaseModule, 'fetchAgentFromDatabase').mockResolvedValue(null)
+    spyOn(databaseModule, 'startAgentRun').mockResolvedValue('run-1')
+    spyOn(databaseModule, 'finishAgentRun').mockResolvedValue(undefined)
+    spyOn(databaseModule, 'addAgentStep').mockResolvedValue('step-1')
+
+    const apiError = new Error('Forbidden') as Error & { statusCode: number; responseBody: string }
+    apiError.statusCode = 403
+    apiError.responseBody = JSON.stringify({
+      error: 'account_suspended',
+      message: 'Your account has been suspended due to billing issues.',
+    })
+
+    spyOn(mainPromptModule, 'callMainPrompt').mockRejectedValue(apiError)
+
+    const client = new CodebuffClient({
+      apiKey: 'test-key',
+    })
+
+    const result = await client.run({
+      agent: 'base2',
+      prompt: 'hello',
+    })
+
+    const output = result.output as { type: 'error'; message: string; statusCode?: number; error?: string }
+    expect(output.message).toBe('Your account has been suspended due to billing issues.')
+    expect(output.statusCode).toBe(403)
+    expect(output.error).toBe('account_suspended')
+  })
+
+  it('falls back to error.message when responseBody is not valid JSON', async () => {
+    spyOn(databaseModule, 'getUserInfoFromApiKey').mockResolvedValue({
+      id: 'user-123',
+      email: 'test@example.com',
+      discord_id: null,
+      referral_code: null,
+      stripe_customer_id: null,
+      banned: false,
+    })
+    spyOn(databaseModule, 'fetchAgentFromDatabase').mockResolvedValue(null)
+    spyOn(databaseModule, 'startAgentRun').mockResolvedValue('run-1')
+    spyOn(databaseModule, 'finishAgentRun').mockResolvedValue(undefined)
+    spyOn(databaseModule, 'addAgentStep').mockResolvedValue('step-1')
+
+    const apiError = new Error('Forbidden') as Error & { statusCode: number; responseBody: string }
+    apiError.statusCode = 403
+    apiError.responseBody = 'not valid json'
+
+    spyOn(mainPromptModule, 'callMainPrompt').mockRejectedValue(apiError)
+
+    const client = new CodebuffClient({
+      apiKey: 'test-key',
+    })
+
+    const result = await client.run({
+      agent: 'base2',
+      prompt: 'hello',
+    })
+
+    const output = result.output as { type: 'error'; message: string; statusCode?: number; error?: string }
+    expect(output.message).toBe('Forbidden')
+    expect(output.statusCode).toBe(403)
+    expect(output.error).toBeUndefined()
+  })
+
   it('preserves user message when callMainPrompt throws an error', async () => {
     spyOn(databaseModule, 'getUserInfoFromApiKey').mockResolvedValue({
       id: 'user-123',

sdk/src/run.ts

@@ -510,15 +510,40 @@ async function runOnce({
     userId,
     signal: signal ?? new AbortController().signal,
   }).catch((error) => {
-    const errorMessage =
+    let errorMessage =
       error instanceof Error ? error.message : String(error ?? '')
     const statusCode = getErrorStatusCode(error)
+
+    // Extract structured error details from the API response body
+    // (e.g., AI SDK's AI_APICallError includes a responseBody with the server's JSON response)
+    let errorCode: string | undefined
+    const responseBody =
+      error && typeof error === 'object' && 'responseBody' in error
+        ? (error as { responseBody: unknown }).responseBody
+        : undefined
+    if (typeof responseBody === 'string') {
+      try {
+        const parsed: unknown = JSON.parse(responseBody)
+        if (parsed && typeof parsed === 'object') {
+          if ('error' in parsed && typeof (parsed as { error: unknown }).error === 'string') {
+            errorCode = (parsed as { error: string }).error
+          }
+          if ('message' in parsed && typeof (parsed as { message: unknown }).message === 'string') {
+            errorMessage = (parsed as { message: string }).message
+          }
+        }
+      } catch {
+        // responseBody wasn't valid JSON; keep original errorMessage
+      }
+    }
+
     resolve({
       sessionState: getCancelledSessionState(errorMessage),
       output: {
         type: 'error',
         message: errorMessage,
         ...(statusCode !== undefined && { statusCode }),
+        ...(errorCode !== undefined && { error: errorCode }),
       },
     })
   })