fix: separate entitlement errors from rate limits to prevent infinite retry loops

- usage_not_included now returns 403 instead of triggering rate limit handling
- adds clear error message for subscription/entitlement issues
- prevents account rotation for non-recoverable errors

fixes #16

Author: ndycode

lib/constants.ts

@@ -18,6 +18,7 @@ export const PROVIDER_ID = "openai";
 /** HTTP Status Codes */
 export const HTTP_STATUS = {
 	OK: 200,
+	FORBIDDEN: 403,
 	UNAUTHORIZED: 401,
 	NOT_FOUND: 404,
 	TOO_MANY_REQUESTS: 429,

lib/request/fetch-helpers.ts

@@ -25,6 +25,50 @@ export interface RateLimitInfo {
         code?: string;
 }
 
+export interface EntitlementError {
+        isEntitlement: true;
+        code: string;
+        message: string;
+}
+
+/**
+ * Checks if an error code indicates an entitlement/subscription issue
+ * These errors should NOT be treated as rate limits because:
+ * 1. They won't resolve by waiting
+ * 2. They won't resolve by switching accounts (all accounts likely have same issue)
+ * 3. User needs to upgrade their subscription
+ */
+export function isEntitlementError(code: string, bodyText: string): boolean {
+        const haystack = `${code} ${bodyText}`.toLowerCase();
+        // "usage_not_included" means the subscription doesn't include this feature
+        // This is different from "usage_limit_reached" which is a temporary quota limit
+        return /usage_not_included|not.included.in.your.plan|subscription.does.not.include/i.test(haystack);
+}
+
+/**
+ * Creates a user-friendly entitlement error response
+ */
+export function createEntitlementErrorResponse(_bodyText: string): Response {
+        const message = 
+                "This model is not included in your ChatGPT subscription. " +
+                "Please check that your account has access to Codex models (requires ChatGPT Plus/Pro). " +
+                "If you recently subscribed, try logging out and back in with `opencode auth login`.";
+        
+        const payload = {
+                error: {
+                        message,
+                        type: "entitlement_error",
+                        code: "usage_not_included",
+                },
+        };
+
+        return new Response(JSON.stringify(payload), {
+                status: 403, // Forbidden - not a rate limit
+                statusText: "Forbidden",
+                headers: { "content-type": "application/json; charset=utf-8" },
+        });
+}
+
 export interface ErrorHandlingResult {
         response: Response;
         rateLimit?: RateLimitInfo;
@@ -219,6 +263,12 @@ export async function handleErrorResponse(
 ): Promise<ErrorHandlingResult> {
         const bodyText = await safeReadBody(response);
         const mapped = mapUsageLimit404WithBody(response, bodyText);
+        
+        // Entitlement errors return a ready-to-use Response with 403 status
+        if (mapped && mapped.status === HTTP_STATUS.FORBIDDEN) {
+                return { response: mapped, rateLimit: undefined, errorBody: undefined };
+        }
+        
         const finalResponse = mapped ?? response;
         const rateLimit = extractRateLimitInfoFromBody(finalResponse, bodyText);
 
@@ -291,8 +341,13 @@ function mapUsageLimit404WithBody(response: Response, bodyText: string): Respons
 		code = "";
 	}
 
+	// Check for entitlement errors first - these should NOT be treated as rate limits
+	if (isEntitlementError(code, bodyText)) {
+		return createEntitlementErrorResponse(bodyText);
+	}
+
 	const haystack = `${code} ${bodyText}`.toLowerCase();
-	if (!/usage_limit_reached|usage_not_included|rate_limit_exceeded|usage limit/i.test(haystack)) {
+	if (!/usage_limit_reached|rate_limit_exceeded|usage limit/i.test(haystack)) {
 		return null;
 	}
 
@@ -313,9 +368,15 @@ function extractRateLimitInfoFromBody(
         const parsed = parseRateLimitBody(bodyText);
 
         const haystack = `${parsed?.code ?? ""} ${bodyText}`.toLowerCase();
+        
+        // Entitlement errors should not be treated as rate limits
+        if (isEntitlementError(parsed?.code ?? "", bodyText)) {
+                return undefined;
+        }
+        
         const isRateLimit =
                 isStatusRateLimit ||
-                /usage_limit_reached|usage_not_included|rate_limit_exceeded|rate_limit|usage limit/i.test(
+                /usage_limit_reached|rate_limit_exceeded|rate_limit|usage limit/i.test(
                         haystack,
                 );
         if (!isRateLimit) return undefined;

test/fetch-helpers.test.ts

@@ -7,6 +7,8 @@ import {
     rewriteUrlForCodex,
     createCodexHeaders,
     handleErrorResponse,
+    isEntitlementError,
+    createEntitlementErrorResponse,
 } from '../lib/request/fetch-helpers.js';
 import type { Auth } from '../lib/types.js';
 import { URL_PATHS, OPENAI_HEADERS, OPENAI_HEADER_VALUES } from '../lib/constants.js';
@@ -200,5 +202,55 @@ describe('Fetch Helpers Module', () => {
 			expect(headers.get(OPENAI_HEADERS.CONVERSATION_ID)).toBeNull();
 			expect(headers.get(OPENAI_HEADERS.SESSION_ID)).toBeNull();
 		});
+
+		it('maps usage_not_included 404 to 403 entitlement error, not rate limit', async () => {
+			const body = {
+				error: {
+					code: 'usage_not_included',
+					message: 'Usage not included in your plan',
+				},
+			};
+			const resp = new Response(JSON.stringify(body), { status: 404 });
+			const { response: result, rateLimit } = await handleErrorResponse(resp);
+			expect(result.status).toBe(403);
+			expect(rateLimit).toBeUndefined();
+			const json = await result.json() as any;
+			expect(json.error.type).toBe('entitlement_error');
+			expect(json.error.message).toContain('not included in your ChatGPT subscription');
+		});
     });
+
+	describe('isEntitlementError', () => {
+		it('returns true for usage_not_included code', () => {
+			expect(isEntitlementError('usage_not_included', '')).toBe(true);
+		});
+
+		it('returns true when body contains "not included in your plan"', () => {
+			expect(isEntitlementError('', 'Usage not included in your plan')).toBe(true);
+		});
+
+		it('returns false for usage_limit_reached (rate limit)', () => {
+			expect(isEntitlementError('usage_limit_reached', '')).toBe(false);
+		});
+
+		it('returns false for rate_limit_exceeded', () => {
+			expect(isEntitlementError('rate_limit_exceeded', '')).toBe(false);
+		});
+
+		it('returns false for generic errors', () => {
+			expect(isEntitlementError('not_found', 'Resource not found')).toBe(false);
+		});
+	});
+
+	describe('createEntitlementErrorResponse', () => {
+		it('returns 403 status with user-friendly message', async () => {
+			const resp = createEntitlementErrorResponse('original body');
+			expect(resp.status).toBe(403);
+			expect(resp.statusText).toBe('Forbidden');
+			const json = await resp.json() as any;
+			expect(json.error.type).toBe('entitlement_error');
+			expect(json.error.code).toBe('usage_not_included');
+			expect(json.error.message).toContain('ChatGPT subscription');
+		});
+	});
 });