HTTP 상태 코드는 서버가 클라이언트의 요청을 어떻게 처리했는지 세 자리 숫자로 요약해 알려주는 신호입니다. 모든 HTTP 응답의 첫 줄(상태 줄)에 코드와 짧은 사유 문구(reason phrase)가 함께 실립니다. 예를 들어 200 OK는 성공을, 404 Not Found는 리소스를 찾지 못했음을 뜻합니다. 사유 문구는 사람이 읽기 위한 참고용일 뿐이고, 프로그램이 실제 판단의 근거로 삼는 것은 숫자 코드입니다.
다섯 개의 클래스
상태 코드는 맨 앞자리 숫자로 다섯 개의 클래스로 나뉩니다. 앞자리만 봐도 응답의 큰 방향을 파악할 수 있도록 설계되어 있어서, 처음 보는 코드라도 대략적인 의미를 짐작할 수 있습니다.
- 1xx (정보): 요청을 받았고 처리를 계속한다는 임시 응답.
100 Continue,101 Switching Protocols. - 2xx (성공): 요청이 정상적으로 수신·이해·수락됨.
200 OK,201 Created,204 No Content. - 3xx (리다이렉션): 요청을 완료하려면 추가 동작(대개 다른 URL로 이동)이 필요함.
301,302,304 Not Modified. - 4xx (클라이언트 오류): 요청 자체에 문제가 있음 — 문법 오류, 권한 부족, 없는 리소스 등.
400,401,403,404. - 5xx (서버 오류): 요청은 정상인데 서버가 처리에 실패함.
500,502,503.
상태 줄을 읽는 법
상태 줄은 HTTP-버전 상태코드 사유문구 형태입니다. 아래는 curl -i로 응답 헤더를 확인했을 때 보이는 전형적인 예입니다.
HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 42
{"error":"user not found","id":"u_92311"}여기서 핵심은 앞자리(4)를 먼저 보고 방향을 잡는 것입니다. 4로 시작하니 클라이언트가 보낸 요청에 문제가 있다는 뜻이고, 뒤의 04가 구체적으로 '대상 리소스가 없음'을 가리킵니다. 서버가 잘못한 게 아니라 요청한 URL이나 식별자가 잘못되었을 가능성을 먼저 의심해야 합니다.
디버깅 빠른 판단 규칙
- 2xx가 나오는데 결과가 이상하다 → 코드가 아니라 응답 본문·비즈니스 로직을 의심하세요. 전송 자체는 성공한 것입니다.
- 4xx → 내 요청을 고쳐야 합니다. URL, 메서드, 헤더(특히
Authorization,Content-Type), 본문 형식을 점검하세요. - 401 vs 403 → 401은 '누구인지 모른다(인증 필요)', 403은 '누구인지 알지만 권한이 없다'.
- 5xx → 서버·백엔드 문제입니다. 재시도(특히 502/503/504)가 도움이 될 수 있고, 서버 로그를 봐야 합니다.
- 3xx →
Location헤더를 따라 어디로 이동하는지 확인하세요. 무한 루프나 http→https 반복이 흔한 함정입니다.
상태 코드는 표준(RFC 9110)이 정의한 공통 어휘이므로, 클라이언트와 서버가 서로의 내부 구현을 몰라도 소통할 수 있게 해 줍니다. 다만 표준을 자의적으로 해석하는 API도 많으므로, 코드는 1차 신호로 삼고 응답 본문의 상세 오류 메시지를 함께 확인하는 습관이 중요합니다.