fix: narrow 404 usage-limit remapping

The 404 error remapper was converting ambiguous responses into 429s
based on free-form body text and generic rate_limit_exceeded codes.
That makes not-found errors look like cooldown signals and feeds weak
rate-limit reasons downstream.

Only remap structured 404 responses that carry explicit usage_limit
codes, while preserving entitlement detection. This keeps quota-limit
signals intact without manufacturing ambiguous 429s from plain text or
generic rate-limit payloads.

Author: ndycode

lib/request/fetch-helpers.ts

@@ -978,8 +978,8 @@ async function safeReadBody(response: Response): Promise<string> {
 }
 
 function mapUsageLimit404WithBody(response: Response, bodyText: string): Response | null {
-        if (response.status !== HTTP_STATUS.NOT_FOUND) return null;
-        if (!bodyText) return null;
+	if (response.status !== HTTP_STATUS.NOT_FOUND) return null;
+	if (!bodyText) return null;
 
 	let code = "";
 	try {
@@ -994,8 +994,11 @@ function mapUsageLimit404WithBody(response: Response, bodyText: string): Respons
 		return createEntitlementErrorResponse(bodyText);
 	}
 
-	const haystack = `${code} ${bodyText}`.toLowerCase();
-	if (!/usage_limit_reached|rate_limit_exceeded|usage limit/i.test(haystack)) {
+	// Only structured quota-limit codes should be remapped from 404 to 429.
+	// Free-text 404 bodies and generic rate_limit_* codes are too ambiguous and
+	// degrade downstream rate-limit reason classification to "unknown".
+	const normalizedCode = code.toLowerCase();
+	if (!normalizedCode.includes("usage_limit")) {
 		return null;
 	}
 

test/fetch-helpers.test.ts

@@ -464,25 +464,40 @@ describe('Fetch Helpers Module', () => {
 	    expect(headers.get('accept')).toBe('text/event-stream');
     });
 
-                it('maps usage-limit 404 errors to 429', async () => {
-                        const body = {
-                                error: {
-                                        code: 'usage_limit_reached',
-                                        message: 'limit reached',
+		it('maps usage-limit 404 errors to 429', async () => {
+			const body = {
+				error: {
+					code: 'usage_limit_reached',
+					message: 'limit reached',
                                 },
                         };
                         const resp = new Response(JSON.stringify(body), { status: 404 });
                         const { response: mapped, rateLimit } = await handleErrorResponse(resp);
                         expect(mapped.status).toBe(429);
                         const json = await mapped.json() as any;
-                        expect(json.error.code).toBe('usage_limit_reached');
-                        expect(rateLimit?.retryAfterMs).toBeGreaterThan(0);
-                });
+			expect(json.error.code).toBe('usage_limit_reached');
+			expect(rateLimit?.retryAfterMs).toBeGreaterThan(0);
+		});
 
-                it('leaves non-usage 404 errors unchanged', async () => {
-                        const body = { error: { code: 'not_found', message: 'nope' } };
-                        const resp = new Response(JSON.stringify(body), { status: 404 });
-                        const { response: result, rateLimit } = await handleErrorResponse(resp);
+		it('maps usage-limit 404 errors to 429 when the signal comes from error.type', async () => {
+			const body = {
+				error: {
+					type: 'usage_limit_reached',
+					message: 'limit reached',
+				},
+			};
+			const resp = new Response(JSON.stringify(body), { status: 404 });
+			const { response: mapped, rateLimit } = await handleErrorResponse(resp);
+			expect(mapped.status).toBe(429);
+			const json = await mapped.json() as { error: { type?: string } };
+			expect(json.error.type).toBe('usage_limit_reached');
+			expect(rateLimit?.retryAfterMs).toBeGreaterThan(0);
+		});
+
+		it('leaves non-usage 404 errors unchanged', async () => {
+			const body = { error: { code: 'not_found', message: 'nope' } };
+			const resp = new Response(JSON.stringify(body), { status: 404 });
+			const { response: result, rateLimit } = await handleErrorResponse(resp);
                         expect(result.status).toBe(404);
                         const json = await result.json() as any;
                         expect(json.error.code).toBe('not_found');
@@ -981,13 +996,30 @@ describe('createEntitlementErrorResponse', () => {
 	});
 
 	describe('handleErrorResponse edge cases', () => {
-		it('handles 404 with non-JSON body containing usage limit text', async () => {
+		it('does not remap 404s with free-text usage-limit messages', async () => {
 			const response = new Response('usage limit exceeded - please try again', { status: 404 });
 
 			const { response: result, rateLimit } = await handleErrorResponse(response);
 
-			expect(result.status).toBe(429);
-			expect(rateLimit?.retryAfterMs).toBeGreaterThan(0);
+			expect(result.status).toBe(404);
+			expect(rateLimit).toBeUndefined();
+		});
+
+		it('does not remap 404s with generic rate_limit_exceeded codes', async () => {
+			const response = new Response(
+				JSON.stringify({
+					error: {
+						code: 'rate_limit_exceeded',
+						message: 'upstream overloaded',
+					},
+				}),
+				{ status: 404 },
+			);
+
+			const { response: result, rateLimit } = await handleErrorResponse(response);
+
+			expect(result.status).toBe(404);
+			expect(rateLimit).toBeUndefined();
 		});
 
 		it('does not treat non-429 rate-limit text as a cooldown signal', async () => {