Next.js API 라우트에서 401과 403을 구분해야 했던 이유

API 응답에서 401과 403을 헷갈리면 사용자 경험이 나빠진다.

401 vs 403

401 Unauthorized: 로그인 정보가 없거나 만료됨

• 사용자가 로그인하지 않은 상태
• 토큰이 만료됨
• 응답: 로그인 페이지로 리다이렉트

403 Forbidden: 권한이 부족함

• 로그인은 했지만 이 리소스에 접근할 권한이 없음
• 관리자만 접근할 수 있는 페이지를 일반 사용자가 접근함
• 응답: "접근 권한이 없습니다" 화면

Next.js에서 구현하기

// pages/api/admin/settings.ts
export default function handler(req, res) {
  const token = req.headers.authorization;

  if (!token) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  const user = verifyToken(token);
  if (user.role !== 'admin') {
    return res.status(403).json({ error: 'Forbidden' });
  }

  res.status(200).json({ settings: {...} });
}

클라이언트에서 다르게 처리하기

try {
  const response = await fetch('/api/admin/settings');

  if (response.status === 401) {
    // 다시 로그인하라
    window.location.href = '/login';
  } else if (response.status === 403) {
    // 접근 불가 화면 표시
    showErrorMessage('이 페이지에 접근할 권한이 없습니다');
  }
} catch (error) {
  handleError(error);
}

이 둘을 구분하면 사용자는 "아, 내가 로그인이 필요하구나" 또는 "아, 나는 이 페이지에 접근할 수 없구나"를 명확히 알 수 있다.