Fix Freebuff 429 error messaging

Author: jahooma

cli/src/hooks/helpers/send-message.ts

@@ -16,8 +16,11 @@ import {
   getFreebuffGateErrorKind,
   isOutOfCreditsError,
   isFreeModeUnavailableError,
+  isFreeModeRateLimitedError,
+  isRateLimitError,
   OUT_OF_CREDITS_MESSAGE,
   FREE_MODE_UNAVAILABLE_MESSAGE,
+  FREEBUFF_RATE_LIMIT_MESSAGE,
 } from '../../utils/error-handling'
 import { formatElapsedTime } from '../../utils/format-elapsed-time'
 import { processImagesForMessage } from '../../utils/image-processor'
@@ -417,6 +420,16 @@ export const handleRunCompletion = (params: {
       return
     }
 
+    if (
+      IS_FREEBUFF &&
+      isRateLimitError(output) &&
+      !isFreeModeRateLimitedError(output)
+    ) {
+      updater.setError(FREEBUFF_RATE_LIMIT_MESSAGE)
+      finalizeAfterError()
+      return
+    }
+
     // Pass the raw error message to setError (displayed in UserErrorBanner without additional wrapper formatting)
     updater.setError(output.message ?? DEFAULT_RUN_OUTPUT_ERROR_MESSAGE)
 
@@ -517,6 +530,15 @@ export const handleRunError = (params: {
     return
   }
 
+  if (
+    IS_FREEBUFF &&
+    isRateLimitError(error) &&
+    !isFreeModeRateLimitedError(error)
+  ) {
+    updater.setError(FREEBUFF_RATE_LIMIT_MESSAGE)
+    return
+  }
+
   // Use setError for all errors so they display in UserErrorBanner consistently
   const errorMessage = errorInfo.message || 'An unexpected error occurred'
   updater.setError(errorMessage)

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

@@ -3,9 +3,12 @@ import { describe, test, expect } from 'bun:test'
 import {
   isOutOfCreditsError,
   isFreeModeUnavailableError,
+  isFreeModeRateLimitedError,
+  isRateLimitError,
   getCountryBlockFromFreeModeError,
   OUT_OF_CREDITS_MESSAGE,
   FREE_MODE_UNAVAILABLE_MESSAGE,
+  FREEBUFF_RATE_LIMIT_MESSAGE,
   createErrorMessage,
 } from '../error-handling'
 
@@ -115,6 +118,42 @@ describe('error-handling', () => {
     })
   })
 
+  describe('isRateLimitError', () => {
+    test('returns true for error with statusCode 429', () => {
+      const error = { statusCode: 429, message: 'Too Many Requests' }
+      expect(isRateLimitError(error)).toBe(true)
+    })
+
+    test('returns true for thrown API error with status 429', () => {
+      const error = { status: 429, message: 'Too Many Requests' }
+      expect(isRateLimitError(error)).toBe(true)
+    })
+
+    test('returns false for non-429 status codes', () => {
+      expect(isRateLimitError({ statusCode: 402 })).toBe(false)
+      expect(isRateLimitError({ statusCode: 500 })).toBe(false)
+    })
+
+    test('returns false for string statusCode', () => {
+      expect(isRateLimitError({ statusCode: '429' })).toBe(false)
+    })
+  })
+
+  describe('isFreeModeRateLimitedError', () => {
+    test('returns true for typed free mode rate limit errors', () => {
+      expect(
+        isFreeModeRateLimitedError({
+          statusCode: 429,
+          error: 'free_mode_rate_limited',
+        }),
+      ).toBe(true)
+    })
+
+    test('returns false for untyped provider rate limit errors', () => {
+      expect(isFreeModeRateLimitedError({ statusCode: 429 })).toBe(false)
+    })
+  })
+
   describe('getCountryBlockFromFreeModeError', () => {
     test('extracts country block details from free-mode unavailable errors', () => {
       const error = {
@@ -177,6 +216,15 @@ describe('error-handling', () => {
     })
   })
 
+  describe('FREEBUFF_RATE_LIMIT_MESSAGE', () => {
+    test('encourages retry without mentioning credits or payment', () => {
+      const message = FREEBUFF_RATE_LIMIT_MESSAGE.toLowerCase()
+      expect(message).toContain('try again')
+      expect(message).not.toContain('credit')
+      expect(message).not.toContain('pay')
+    })
+  })
+
   describe('createErrorMessage', () => {
     test('creates message from Error object', () => {
       const error = new Error('Something went wrong')

cli/src/utils/error-handling.ts

@@ -61,6 +61,22 @@ export const isFreeModeUnavailableError = (error: unknown): boolean => {
   return false
 }
 
+/**
+ * Check if an error indicates rate limiting.
+ * Agent outputs use statusCode; some thrown API errors use status.
+ */
+export const isRateLimitError = (error: unknown): boolean => {
+  if (!error || typeof error !== 'object') return false
+  const statusCode = (error as { statusCode?: unknown }).statusCode
+  const status = (error as { status?: unknown }).status
+  return statusCode === 429 || status === 429
+}
+
+export const isFreeModeRateLimitedError = (error: unknown): boolean => {
+  if (!isRateLimitError(error)) return false
+  return (error as { error?: unknown }).error === 'free_mode_rate_limited'
+}
+
 export const getCountryBlockFromFreeModeError = (
   error: unknown,
 ): {
@@ -134,6 +150,9 @@ export const getFreebuffGateErrorKind = (
 
 export const OUT_OF_CREDITS_MESSAGE = `Out of credits. Please add credits at ${defaultAppUrl}/usage`
 
+export const FREEBUFF_RATE_LIMIT_MESSAGE =
+  'Freebuff is temporarily busy. Please try again in a moment.'
+
 export const FREE_MODE_UNAVAILABLE_MESSAGE = IS_FREEBUFF
   ? 'Freebuff is not available in your country.'
   : 'Free mode is not available in your country. You can use another mode to continue.'

docs/error-schema.md

@@ -161,6 +161,9 @@ isOutOfCreditsError(output)       → shows OUT_OF_CREDITS_MESSAGE
 
 // Checks statusCode === 403 && error === 'free_mode_unavailable'
 isFreeModeUnavailableError(output) → shows FREE_MODE_UNAVAILABLE_MESSAGE
+
+// Freebuff only: checks statusCode === 429 after waiting-room/free-mode quota errors
+isRateLimitError(output)          → shows FREEBUFF_RATE_LIMIT_MESSAGE
 ```
 
 For all other errors, the raw `output.message` is displayed in the `UserErrorBanner`.