Allow free requests to go through even when subscription depleted and credit use not enabled

Author: jahooma

web/src/app/api/v1/chat/completions/__tests__/completions.test.ts

@@ -420,6 +420,39 @@ describe('/api/v1/chat/completions POST endpoint', () => {
       expect(body.message).toContain(expectedResetCountdown)
       expect(body.message).not.toContain(nextQuotaReset)
     })
+
+    it('skips credit check when in FREE mode even with 0 credits', async () => {
+      const req = new NextRequest(
+        'http://localhost:3000/api/v1/chat/completions',
+        {
+          method: 'POST',
+          headers: { Authorization: 'Bearer test-api-key-no-credits' },
+          body: JSON.stringify({
+            model: 'test/test-model',
+            stream: false,
+            codebuff_metadata: {
+              run_id: 'run-123',
+              client_id: 'test-client-id-123',
+              cost_mode: 'free',
+            },
+          }),
+        },
+      )
+
+      const response = await postChatCompletions({
+        req,
+        getUserInfoFromApiKey: mockGetUserInfoFromApiKey,
+        logger: mockLogger,
+        trackEvent: mockTrackEvent,
+        getUserUsageData: mockGetUserUsageData,
+        getAgentRunFromId: mockGetAgentRunFromId,
+        fetch: mockFetch,
+        insertMessageBigquery: mockInsertMessageBigquery,
+        loggerWithContext: mockLoggerWithContext,
+      })
+
+      expect(response.status).toBe(200)
+    })
   })
 
   describe('Successful responses', () => {
@@ -549,6 +582,52 @@ describe('/api/v1/chat/completions POST endpoint', () => {
       expect(body.message).toContain('Enable "Continue with credits"')
     })
 
+    it('skips subscription limit check when in FREE mode even with fallback disabled', async () => {
+      const weeklyLimitError: BlockGrantResult = {
+        error: 'weekly_limit_reached',
+        used: 3500,
+        limit: 3500,
+        resetsAt: new Date(Date.now() + 3 * 24 * 60 * 60 * 1000),
+      }
+      const mockEnsureSubscriberBlockGrant = mock(async () => weeklyLimitError)
+      const mockGetUserPreferences: GetUserPreferencesFn = mock(async () => ({
+        fallbackToALaCarte: false,
+      }))
+
+      const freeModeRequest = new NextRequest(
+        'http://localhost:3000/api/v1/chat/completions',
+        {
+          method: 'POST',
+          headers: { Authorization: 'Bearer test-api-key-123' },
+          body: JSON.stringify({
+            model: 'test/test-model',
+            stream: false,
+            codebuff_metadata: {
+              run_id: 'run-123',
+              client_id: 'test-client-id-123',
+              cost_mode: 'free',
+            },
+          }),
+        },
+      )
+
+      const response = await postChatCompletions({
+        req: freeModeRequest,
+        getUserInfoFromApiKey: mockGetUserInfoFromApiKey,
+        logger: mockLogger,
+        trackEvent: mockTrackEvent,
+        getUserUsageData: mockGetUserUsageData,
+        getAgentRunFromId: mockGetAgentRunFromId,
+        fetch: mockFetch,
+        insertMessageBigquery: mockInsertMessageBigquery,
+        loggerWithContext: mockLoggerWithContext,
+        ensureSubscriberBlockGrant: mockEnsureSubscriberBlockGrant,
+        getUserPreferences: mockGetUserPreferences,
+      })
+
+      expect(response.status).toBe(200)
+    })
+
     it('returns 429 when block exhausted and fallback disabled', async () => {
       const blockExhaustedError: BlockGrantResult = {
         error: 'block_exhausted',

web/src/app/api/v1/chat/completions/_post.ts

@@ -1,5 +1,6 @@
 import { AnalyticsEvent } from '@codebuff/common/constants/analytics-events'
 import { BYOK_OPENROUTER_HEADER } from '@codebuff/common/constants/byok'
+import { isFreeMode } from '@codebuff/common/constants/free-agents'
 import { getErrorObject } from '@codebuff/common/util/error'
 import { pluralize } from '@codebuff/common/util/string'
 import { env } from '@codebuff/internal/env'
@@ -199,12 +200,16 @@ export async function postChatCompletions(params: {
       logger,
     })
 
-    // Check user credits
+    // Check if the request is in FREE mode (costs 0 credits for allowed agent+model combos)
+    const costMode = typedBody.codebuff_metadata?.cost_mode
+    const isFreeModeRequest = isFreeMode(costMode)
+
+    // Check user credits (skip for FREE mode since those requests cost 0 credits)
     const {
       balance: { totalRemaining },
       nextQuotaReset,
     } = await getUserUsageData({ userId, logger })
-    if (totalRemaining <= 0) {
+    if (totalRemaining <= 0 && !isFreeModeRequest) {
       trackEvent({
         event: AnalyticsEvent.CHAT_COMPLETIONS_INSUFFICIENT_CREDITS,
         userId,
@@ -294,7 +299,7 @@ export async function postChatCompletions(params: {
             ? await getUserPreferences({ userId, logger })
             : { fallbackToALaCarte: true } // Default to allowing a-la-carte if no preference function
 
-          if (!preferences.fallbackToALaCarte) {
+          if (!preferences.fallbackToALaCarte && !isFreeModeRequest) {
             const resetTime = blockGrantResult.resetsAt
             const resetCountdown = formatQuotaResetCountdown(resetTime.toISOString())
             const limitType = isWeeklyLimitError(blockGrantResult) ? 'weekly' : '5-hour session'