흔한 에러들 — CORS, 404, 500 해결법

웹 개발을 하다 보면 반복적으로 만나는 에러가 있습니다. 이 에러들의 의미만 알면 절반은 해결된 셈입니다.

CORS 에러 — 가장 당혹스러운 에러 1위. `Access to fetch at 'https://api.example.com' from origin 'http://localhost:3000' has been blocked by CORS policy` 원인: 브라우저는 보안상 다른 출처(도메인)의 API를 호출하는 것을 기본적으로 차단합니다. `localhost:3000`에서 `api.example.com`은 다른 출처이므로 차단됩니다. 비유: 아파트 경비원이 '외부인 출입 금지'로 설정되어 있는 상황. 경비원(브라우저)에게 '이 사람은 허용된 사람이에요'라고 알려줘야 합니다.

// CORS 해결법 1: 백엔드에서 허용 헤더 추가 (가장 정석)
// Next.js API Route 예시
export async function GET() {
  return new Response(JSON.stringify({ data: "hello" }), {
    headers: {
      "Access-Control-Allow-Origin": "http://localhost:3000",
      "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE",
    },
  });
}

// CORS 해결법 2: Next.js rewrites로 프록시 (프론트에서 해결)
// next.config.ts
const nextConfig = {
  async rewrites() {
    return [
      {
        source: "/api/external/:path*",
        destination: "https://api.example.com/:path*",
      },
    ];
  },
};

디버깅 순서 체계 — 에러를 만났을 때 당황하지 않고 따라갈 수 있는 5단계: 1. 에러 메시지를 읽는다 — 90%의 답이 에러 메시지 안에 있습니다. 2. 브라우저 개발자 도구(F12) → Console 탭 — 프론트엔드 에러 확인. 3. 터미널 로그 — 백엔드(서버) 에러 확인. `npm run dev` 실행 중인 터미널에 빨간 글씨가 뜹니다. 4. Network 탭 — API 호출의 Status Code, Request/Response 확인. 5. Claude Code에게 에러 메시지를 그대로 붙여넣기 — Claude가 원인과 해결책을 알려줍니다. 가장 중요한 원칙: 에러 메시지를 무시하지 마세요. 에러는 '뭐가 잘못됐는지' 정확히 알려주는 친절한 메시지입니다.

실전 팁: Claude Code에게 에러를 물어볼 때, "안 돼요"보다 에러 메시지를 그대로 복사해서 보내세요. - 나쁜 예: "API가 안 돼요." - 좋은 예: "`GET /api/users` 호출 시 `500 Internal Server Error` 발생. 터미널에 `Error: connect ECONNREFUSED 127.0.0.1:5432` 출력." 두 번째 질문을 받은 Claude는 즉시 'DB 연결 실패 → PostgreSQL이 실행 중인지 확인'이라고 답할 수 있습니다.