HTTP 상태 코드 참조

HTTP 상태 코드 참조는 HTTP 사양에 정의된 모든 상태 코드(100 Continue부터 511 Network Authentication Required까지)의 완전히 검색 가능한 색인입니다. 각 항목에는 표준 이름, 이를 정의하는 RFC, 코드가 실제로 의미하는 바, 보낼 때와 보내지 말아야 할 때, 그리고 실제 코드베이스에서 겪기 쉬운 흔한 함정이 표시됩니다. 실시간 필터와 카테고리 칩을 사용하면 단 한 번의 클릭으로 클래스 간을 이동할 수 있습니다.

평면적인 치트 시트와 달리, 이 도구는 각 코드에 고유한 마이크로 페이지를 제공하며 색상별로 구분된 세 개의 패널(권장 / 금지 / 함정)과 Express.js, Django, FastAPI 및 Go net/http를 위한 바로 붙여넣을 수 있는 핸들러를 포함하고 있습니다. 애니메이션 방식의 와이어 다이어그램은 클라이언트에서 서버로 이동하는 요청과 다시 역방향으로 흐르는 선택된 상태를 보여주며, 상태 코드가 회선 상에서 실제로 무엇을 나타내는지 학습하는 초보자에게 유용합니다.

상태 코드 참조가 중요한 이유

HTTP 상태 코드 참조 사용 방법

1. 빠른 조회. 상단의 검색창에 코드(404)나 이름 조각(teapot, gateway)을 입력하고 제출하세요. 일치하는 항목이 전체 상세 패널과 함께 열립니다.
2. 클래스별 탐색. 5개의 칩(1xx, 2xx, 3xx, 4xx, 5xx) 중 하나를 클릭하여 그리드를 해당 클래스로 필터링하세요. 초기화하려면 전체를 클릭하세요.
3. 실시간 필터. 그리드 바로 위의 필터 상자는 타이핑에 따라 카드를 좁혀줍니다. too many나 precondition처럼 이름의 일부만 기억날 때 유용합니다.
4. 코드 검사. 아무 카드나 클릭하여 상세 패널을 여세요. 의미, 사용 시기, 사용하지 말아야 할 때, 흔한 함정, 그리고 4개 프레임워크 스니펫 블록을 볼 수 있습니다.
5. 스니펫 복사. 탭 전환기와 작은 복사 버튼을 사용하여 바로 붙여넣을 수 있는 핸들러를 가져오세요.
6. 인접 코드 비교. 상세 패널의 끝에는 신속한 병렬 비교를 위해 동일한 클래스(1xx / 2xx / 3xx / 4xx / 5xx)의 형제 카드들이 표시됩니다.

다섯 가지 HTTP 상태 클래스 한눈에 보기

자주 혼동하는 쌍

• 401 대 403. 401은 인증되지 않음을 의미하며 요청에 유효한 자격 증명이 부족함을 나타냅니다. 403은 인증되었으나 허용되지 않음을 의미하며 자격 증명은 정상이지만 사용자에게 권한이 부족함을 나타냅니다.
• 404 대 410. 404는 알 수 없음을 의미하며 어딘가에 존재할 수도 있고 오타일 수도 있음을 나타냅니다. 410은 의도적으로 제거됨을 의미하며 검색 엔진이 인덱스에서 이를 삭제해야 함을 나타냅니다.
• 301 대 302 대 307 대 308. 301 / 308은 영구적(308은 메서드와 본문을 엄격히 보존), 302 / 307은 일시적(307은 메서드와 본문을 엄격히 보존)입니다. POST / PUT / PATCH 리다이렉트에는 307 / 308을 사용하세요.
• 400 대 422. 400은 요청 본문의 형식이 잘못되었음을 의미합니다(잘못된 JSON, 누락된 필드). 422는 본문 구문 분석은 정상적으로 되었으나 값들이 비즈니스 규칙을 통과하지 못했음을 의미합니다(잘못된 이메일 형식, 범위를 벗어난 수량).
• 502 대 503 대 504. 502는 업스트림에서 잘못된 데이터를 보냈음을 의미합니다. 503은 서버가 과부하 상태이거나 유지보수 중임을 의미합니다. 504는 업스트림이 제시간에 응답하지 않았음을 의미합니다.
• 409 대 412. 409는 리소스의 현재 상태와 충돌이 발생했음을 의미합니다. 412는 특히 전제조건 헤더(If-Match, If-Unmodified-Since)의 평가 결과가 거짓(false)임을 의미합니다.

특정 상태 코드와 쌍을 이루는 헤더

• 201 Created — 새 리소스를 가리키는 Location 헤더가 포함되어야 합니다.
• 301 / 302 / 307 / 308 — 대상 URL이 포함된 Location 헤더가 반드시 있어야 합니다.
• 304 Not Modified — 200 응답에 표시되었을 헤더들(ETag, Cache-Control, Vary)을 반드시 그대로 반영해야 합니다.
• 401 Unauthorized — 허용되는 인증 스키마(Basic, Bearer)가 나열된 WWW-Authenticate 헤더가 반드시 포함되어야 합니다.
• 405 Method Not Allowed — 허용되는 메서드들이 나열된 Allow 헤더가 반드시 포함되어야 합니다.
• 413 / 429 / 503 — 클라이언트가 올바르게 대기 후 재시도할 수 있도록 종종 Retry-After(초 단위 또는 HTTP-날짜)를 포함합니다.
• 416 Range Not Satisfiable — Content-Range: bytes */<length> 형식을 반드시 포함해야 합니다.

거의 항상 무시해도 좋은 상태 코드

몇몇 코드들은 기술적으로는 유효하지만 현대 API에서는 극히 드물게 사용됩니다: 305 Use Proxy(더 이상 사용되지 않음), 306(예약됨, 사용되지 않음), 305, 506 Variant Also Negotiates, 510 Not Extended, 및 508 Loop Detected. 대부분은 역사적인 이유로 레지스트리에 유지되고 있습니다. 라이브러리나 미들웨어에서 이러한 코드 중 하나를 내보낸다면 이를 특별히 처리하라는 힌트가 아닌 해당 라이브러리의 버그 리포트로 취급하세요.

자주 묻는 질문 (FAQ)

이 도구에는 RFC 9110 이외의 RFC 코드도 포함되어 있나요?

네. RFC 9110(HTTP 시맨틱), RFC 6585(추가 4xx / 5xx), RFC 4918(WebDAV), RFC 5842(WebDAV 바인딩), RFC 7725(451), RFC 8297(103 Early Hints), RFC 8470(425 Too Early), 그리고 만우절 농담으로 유명한 RFC 2324(418 Teapot)를 다룹니다.

이 코드들은 HTTP/2 및 HTTP/3에서도 유효한가요?

네. 상태 코드 시맨틱은 버전 독립적인 HTTP 시맨틱 문서인 RFC 9110에 정의되어 있습니다. HTTP/2(RFC 9113) 및 HTTP/3(RFC 9114)는 프레이밍과 전송 방식만 변경합니다.

특정 코드로 직접 링크할 수 있나요?

검색창에 단일 코드(예: 404)를 입력하여 제출하면 폼 하단에 상세 패널이 로드됩니다. 해당 URL에는 검색어가 표시되며 이를 공유하더라도 안전합니다. 링크를 열면 동일한 결과가 로드됩니다.

왜 내 프레임워크에서는 418 코드를 반환할 수 없나요?

일부 HTTP 라이브러리의 구버전은 내부 레지스트리에 없는 코드의 출력을 거부합니다. 해결 방법은 라이브러리를 업그레이드하거나 가능하면 상태 라인(status line)을 수동으로 작성하는 것입니다.

API가 오류 본문과 함께 200 코드를 반환해도 되나요?

아니요. 모니터링, 재시도 및 중간 장치들은 모두 2xx가 성공을 의미한다고 가정합니다. 구조화된 오류 정보를 반환해야 하는 경우, 적절한 4xx 또는 5xx 코드를 반환하고 본문 내부에 구조화된 상세 내용을 넣으세요. HTTP API용 Problem Details 형식(RFC 9457)이 좋은 템플릿입니다.

HTTP 상태 코드의 공인된 레지스트리가 있나요?

네. IANA가 iana.org/assignments/http-status-codes에서 레지스트리를 관리하고 있습니다. 이 도구는 해당 레지스트리 및 가장 자주 인용되는 RFC들과 동기화된 상태를 유지합니다.