nanocode/skills/diagnose-api-mismatch/SKILL.md

name, description

name	description
diagnose-api-mismatch	Compare frontend fetch URLs and auth configurations against backend route definitions to identify endpoint path mismatches and missing credentials causing 404 or 401 errors. Use when debugging API call failures, auth issues between frontend and backend, or when reviewing full-stack code for integration bugs.

Diagnose API Mismatch

Systematic workflow to find and fix frontend/backend API integration bugs.

When to Use

• Frontend fetch returns 404 or 401
• SSO/cookie auth works in browser but fails in code
• Suspected URL path mismatch between frontend call and backend route
• Reviewing full-stack changes for integration correctness

Steps

1. Locate the frontend fetch call

   • Use grep to find fetch(, axios, or $.ajax in the frontend codebase
   • Extract the full URL/path being requested

2. Locate the backend route definition

   • Search backend route files (Express, FastAPI, Flask, etc.) for the corresponding endpoint
   • Note the exact path, HTTP method, and auth middleware

3. Compare paths

   • Check for missing/extra path segments (e.g., /api prefix, /fetch suffix)
   • Verify HTTP method matches (GET vs POST)

4. Compare auth configuration

   • Check if backend expects Bearer token, cookie session, or both
   • Check if frontend fetch includes:
     • credentials: 'include' (required for SSO cookies)
     • Authorization: Bearer <token> header (required for token auth)
   • If using dual auth (cookie + Bearer), ensure both are sent when available

5. Identify the fix

   • Path mismatch → update frontend URL or backend route
   • Missing credentials → add credentials: 'include'
   • Missing header → conditionally attach Authorization when token exists
   • Wrong method → align frontend and backend

Output Format

Report findings as:

Issue: <404|401|METHOD_MISMATCH|etc.>
Frontend: <file> calls <method> <url>
Backend:  <file> defines <method> <route> with <auth>
Root cause: <explanation>
Fix: <specific code change>

Example

Problem: CrawlEdit.jsx article crawl fails with HTTP 401.

Diagnosis:

• Frontend (CrawlEdit.jsx): fetch('/api/crawl') — no credentials option, no Authorization header
• Backend (routes/crawl.js): router.post('/api/crawl', requireAuth) — accepts Bearer token or SSO cookie

Root cause: Raw fetch omits SSO cookies by default, and no Bearer token is attached.

Fix:

const token = localStorage.getItem('token');
fetch('/api/crawl', {
  method: 'POST',
  credentials: 'include',
  headers: {
    ...(token && { 'Authorization': `Bearer ${token}` }),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(data),
});

Tools

• grep — find fetch calls and route definitions
• read_file — inspect specific frontend/backend files
• edit_file / write_file — apply fixes