HTTP 상태 코드

상태 코드 카테고리

• 1xx 정보: 임시 응답 — 요청 수신됨, 서버가 아직 처리 중.
• 2xx 성공: 요청이 수신, 이해, 수락됨.
• 3xx 리다이렉션: 요청을 완료하려면 추가 조치 필요.
• 4xx 클라이언트 오류: 요청에 잘못된 구문이 있거나 처리 불가.
• 5xx 서버 오류: 서버가 유효한 요청 처리에 실패.

API에서 어떤 상태 코드를 쓸까

401과 403. 401은 서버가 요청자를 식별하지 못한 상태이며, 401을 보내는 서버는 WWW-Authenticate 헤더도 반드시 보내야 합니다(RFC 9110 §15.5.2). 403은 요청자를 알지만 이 작업을 허용하지 않는 상태입니다. 리소스가 존재한다는 사실을 숨겨야 하면 403 대신 404를 보낼 수 있습니다(§15.5.4).

리다이렉트와 요청 메서드. 역사적인 이유로 브라우저는 301과 302를 따라갈 때 POST를 GET으로 바꿀 수 있습니다(§15.4.2). 307과 308은 메서드와 본문을 유지해야 합니다. 폼 POST를 POST로 유지해야 하면 307이나 308을 쓰세요.

코드와 함께 보내는 헤더

JavaScript에서 처리하기

fetch()는 4xx나 5xx에서 reject하지 않습니다. 네트워크 오류일 때만 reject하므로 res.ok(200–299이면 true)나 res.status를 확인하세요.

const res = await fetch('/api/orders', { method: 'POST', body });
if (res.status === 401) return redirectToLogin();
if (res.status === 429) {
  const wait = Number(res.headers.get('Retry-After') ?? 60);
  return retryAfter(wait);
}
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const order = await res.json();

제한 사항

• 등록된 코드 61개. 목록은 IANA 레지스트리를 따릅니다. nginx 499나 Cloudflare 520–526처럼 특정 제품만 쓰는 코드는 없습니다.
• 두 코드는 예전 이름입니다. 목록의 413 Payload Too Large와 422 Unprocessable Entity는 RFC 9110에서 Content Too Large와 Unprocessable Content로 이름이 바뀌었습니다.
• 설명은 영어로만 나옵니다. 모든 언어 페이지에서 이름과 설명이 영어입니다. 검색은 코드, 이름, 영어 설명의 단어와 일치하는 항목을 찾으므로 「리다이렉트」로는 결과가 없고 redirect로 검색해야 합니다.