fix(proxy): handle 404 with model-not-found guidance

src/app/api/openrouter/[...path]/route.ts

@@ -592,6 +592,8 @@ export async function POST(request: NextRequest): Promise<NextResponseType<unkno
       request: requestBodyParsed,
       response,
       isUserByok: !!userByok,
+      feature,
+      balance: (await balanceAndSettingsPromise).balance,
     });
     if (errorResponse) {
       return errorResponse;

src/lib/llm-proxy-helpers.ts

@@ -126,6 +126,7 @@ const byokErrorMessages: Record<number, string> = {
   401: '[BYOK] Your API key is invalid or has been revoked. Please check your API key configuration.',
   402: '[BYOK] Your API account has insufficient funds. Please check your billing details with your API provider.',
   403: '[BYOK] Your API key does not have permission to access this resource. Please check your API key permissions.',
+  404: '[BYOK] The requested model does not exist or is no longer available. Please check the model name and your API provider.',
   429: '[BYOK] Your API key has hit its rate limit. Please try again later or check your rate limit settings with your API provider.',
 };
 
@@ -142,11 +143,15 @@ export async function makeErrorReadable({
   request,
   response,
   isUserByok,
+  feature,
+  balance,
 }: {
   requestedModel: string;
   request: GatewayRequest;
   response: Response;
   isUserByok: boolean;
+  feature: FeatureValue | null;
+  balance: number;
 }) {
   if (response.status < 400) {
     return undefined;
@@ -161,6 +166,17 @@ export async function makeErrorReadable({
         { status: response.status }
       );
     }
+
+  }
+
+  if (response.status === 404) {
+    const recommendedModel = balance <= 0 ? KILO_AUTO_FREE_MODEL : KILO_AUTO_BALANCED_MODEL;
+    const recommendation =
+      feature === 'kiloclaw' || feature === 'openclaw'
+        ? `The model "${requestedModel}" does not exist or is no longer available. We recommend switching to ${recommendedModel.name}: /model kilocode/${recommendedModel.id}`
+        : `The model "${requestedModel}" does not exist or is no longer available. We recommend switching to ${recommendedModel.id}.`;
+    warnExceptInTest(`Responding with 404 ${recommendation}`);
+    return NextResponse.json({ error: recommendation, message: recommendation }, { status: 404 });
   }
 
   // Sometimes we get generic or nonsensical errors when the context length is exceeded