fix(api): classify compare route GitHub errors (JhaSourav07#2205)

## Description

Fixes JhaSourav07#2204

## Pillar

- [x] 🛠️ Other (Bug fix, refactoring, docs)

## What changed

The `/api/compare` route used `Promise.allSettled`, but both rejected
fetch branches returned `404` unconditionally. That made GitHub rate
limits and upstream failures look like missing users.

This PR adds a small helper that classifies rejected GitHub dashboard
fetches before responding:

- not-found / could-not-resolve errors still return `404`
- rate-limit style errors return `403` with the existing GitHub
rate-limit message
- other upstream failures return `500` instead of being mislabeled as
not-found

Tests were added for user1 rate-limit, user2 rate-limit, and a
non-rate-limit upstream failure.

## Visual Preview

N/A - JSON API status-code fix only.

## Local verification

- `npm run test -- app/api/compare/route.test.ts` passed
- `npm run format:check` passed
- `npm run lint` passed with one existing warning in
`components/WallOfLove.tsx`
- `npm run typecheck` passed
- `npm run test` passed: 83 files, 1438 passed, 1 expected fail
- `npm run build` fails locally with an opaque webpack error; this
appears environment/upstream-local because CI build passed on the prior
PR after the same local failure pattern

## GSSoC 2026

This is raised and fixed under GSSoC 2026. Please add the relevant
GSSoC/level labels if they do not sync from the issue automatically.

## Checklist before requesting a review:

- [x] I have read the `CONTRIBUTING.md` file.
- [x] I have tested these changes locally
(`localhost:3000/api/streak?user=YOUR_USERNAME`).
- [x] I have run `npm run format` / `npm run format:check` and `npm run
lint` locally.
- [x] I have run `npm run test` and all tests pass locally.
- [x] My commits follow the Conventional Commits format.
- [x] I have updated `README.md` if I added a new theme or URL
parameter.
- [x] I have starred the repo.
- [x] I have made sure that I have only one commit to merge in this PR.
- [x] The SVG output matches the CommitPulse quality standard.

Author: JhaSourav07

app/api/compare/route.test.ts

@@ -90,4 +90,38 @@ describe('GET /api/compare', () => {
     const res = await GET(makeRequest('user1=octocat&user2=ghost123'));
     expect(res.status).toBe(404);
   });
+
+  it('returns 403 when the user1 fetch hits a GitHub rate limit', async () => {
+    vi.mocked(getFullDashboardData).mockRejectedValueOnce(new Error('API Rate Limit Exceeded'));
+
+    const res = await GET(makeRequest('user1=octocat&user2=torvalds'));
+
+    expect(res.status).toBe(403);
+    const data = await res.json();
+    expect(data.error).toBe('GitHub API rate limit reached. Please configure GITHUB_TOKEN.');
+  });
+
+  it('returns 403 when the user2 fetch hits a GitHub rate limit', async () => {
+    vi.mocked(getFullDashboardData)
+      .mockResolvedValueOnce({ calendar: { totalContributions: 0, weeks: [] } } as never)
+      .mockRejectedValueOnce(new Error('GitHub GraphQL API returned status 403'));
+
+    const res = await GET(makeRequest('user1=octocat&user2=torvalds'));
+
+    expect(res.status).toBe(403);
+    const data = await res.json();
+    expect(data.error).toBe('GitHub API rate limit reached. Please configure GITHUB_TOKEN.');
+  });
+
+  it('returns 500 for non-rate-limit upstream failures instead of reporting not found', async () => {
+    vi.mocked(getFullDashboardData).mockRejectedValueOnce(
+      new Error('GitHub GraphQL API returned status 500')
+    );
+
+    const res = await GET(makeRequest('user1=octocat&user2=torvalds'));
+
+    expect(res.status).toBe(500);
+    const data = await res.json();
+    expect(data.error).toContain('GitHub GraphQL API returned status 500');
+  });
 });

app/api/compare/route.ts

@@ -4,6 +4,38 @@ import { compareParamsSchema } from '@/lib/validations';
 
 export const revalidate = 3600;
 
+function buildCompareFetchErrorResponse(user: string, reason: unknown): NextResponse {
+  const message = reason instanceof Error ? reason.message : 'Unknown error';
+  const lowerMessage = message.toLowerCase();
+
+  if (lowerMessage.includes('not found') || lowerMessage.includes('could not resolve')) {
+    return NextResponse.json(
+      {
+        error: `Failed to fetch data for "${user}": ${message}`,
+      },
+      { status: 404 }
+    );
+  }
+
+  if (
+    lowerMessage.includes('rate limit') ||
+    message.includes('API limit reached') ||
+    message.includes('status 403')
+  ) {
+    return NextResponse.json(
+      { error: 'GitHub API rate limit reached. Please configure GITHUB_TOKEN.' },
+      { status: 403 }
+    );
+  }
+
+  return NextResponse.json(
+    {
+      error: `Failed to fetch data for "${user}": ${message}`,
+    },
+    { status: 500 }
+  );
+}
+
 export async function GET(request: Request) {
   const { searchParams } = new URL(request.url);
 
@@ -26,21 +58,11 @@ export async function GET(request: Request) {
     ]);
 
     if (result1.status === 'rejected') {
-      return NextResponse.json(
-        {
-          error: `Failed to fetch data for "${user1}": ${result1.reason?.message || 'Unknown error'}`,
-        },
-        { status: 404 }
-      );
+      return buildCompareFetchErrorResponse(user1, result1.reason);
     }
 
     if (result2.status === 'rejected') {
-      return NextResponse.json(
-        {
-          error: `Failed to fetch data for "${user2}": ${result2.reason?.message || 'Unknown error'}`,
-        },
-        { status: 404 }
-      );
+      return buildCompareFetchErrorResponse(user2, result2.reason);
     }
 
     return NextResponse.json({