HTTP 상태 코드
1xx~5xx 모든 HTTP 상태 코드를 설명과 함께 검색할 수 있는 완전한 참조 문서. 무료, 브라우저에서 처리.
- 브라우저에서 처리
- 도구 입력을 ZeroTool 서버에 업로드하지 않습니다
- 무료 · 회원가입 불필요
WeChat으로 스캔하여 공유
예시·자세한 설명·자주 묻는 질문 실제 출력이 있는 예시, 다른 도구와의 차이, 자주 묻는 질문.
상태 코드 카테고리
- 1xx 정보: 임시 응답 — 요청 수신됨, 서버가 아직 처리 중.
- 2xx 성공: 요청이 수신, 이해, 수락됨.
- 3xx 리다이렉트: 요청을 완료하려면 추가 조치 필요.
- 4xx 클라이언트 오류: 요청에 잘못된 구문이 있거나 처리 불가.
- 5xx 서버 오류: 서버가 유효한 요청 처리에 실패.
네이버 오픈 API 오류 코드와 맞춰 보기
네이버 개발자센터의 오류 코드 문서는 오픈 API가 돌려주는 HTTP 상태 코드와 원인을 표로 정리해 둡니다. 같은 코드라도 일반적인 의미와 네이버에서의 원인이 다를 수 있으니, 이 도구의 영어 설명과 함께 보세요.
403. 이 도구의 설명은 Server understood the request but refuses to authorize it.입니다. 네이버 문서는 HTTPS가 아닌 HTTP로 호출한 경우도 403의 원인으로 듭니다. 키를 다시 발급받기 전에 요청 URL이 https://인지부터 확인하세요.
403 Forbidden
429. 네이버는 하루 허용량을 넘었을 때와, 검색 API의 초당 호출량을 넘었을 때 모두 429를 돌려줍니다. 하루 한도는 기다려도 그날 안에는 풀리지 않으므로, 문서는 하루 허용량 초과 시 제휴 신청을 안내합니다. 이 도구에서 영어로 too many를 검색하면 다음과 같습니다.
429 Too Many Requests
500. 문서에는 API 서버 오류뿐 아니라, 필수 요청 변수가 없거나 요청 변수 값을 URL 인코딩하지 않은 경우도 500의 원인으로 적혀 있습니다. 500이라고 서버 장애로 단정하지 말고 요청 변수부터 확인하세요.
설명은 영어라서 한국어로 검색하면 결과가 없습니다. 예를 들어 한도를 검색하면 다음과 같이 표시됩니다.
일치하는 상태 코드가 없습니다.
API에서 어떤 상태 코드를 쓸까
| 상황 | 코드 |
|---|---|
GET으로 리소스 반환 | 200 |
POST로 리소스 생성 | 201 (Location 헤더 포함) |
성공했지만 본문 없음 (주로 DELETE) | 204 |
| 본문이 올바른 JSON이 아니거나 구문 오류 | 400 |
| 토큰이 없거나 유효하지 않음 | 401 |
| 토큰은 유효하지만 권한 없음 | 403 |
| 리소스가 없음 | 404 |
| 중복 (이미 가입된 이메일 등) | 409 |
| 본문은 파싱되지만 업무 규칙 위반 (종료일이 시작일보다 앞섬) | 422 |
| 요청 한도 초과 | 429 |
| 처리되지 않은 예외 | 500 |
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을 쓰세요.
코드와 함께 보내는 헤더
| 코드 | 헤더 | 규정 |
|---|---|---|
| 201 | Location: /api/users/456 | 새 리소스를 가리킴 |
| 401 | WWW-Authenticate: Bearer realm="api" | 필수 |
| 405 | Allow: GET, POST | 필수 (§15.5.6) |
| 429, 503 | Retry-After: 60 | 선택. 초 또는 HTTP 날짜 (RFC 6585 §4) |
| 304 | — | 본문 없음. 클라이언트가 캐시를 사용 |
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();
제한 사항
- IANA 레지스트리의 코드 64개를 모두 수록. 목록은 IANA HTTP Status Code Registry(마지막 갱신 2025-09-15)와 코드 단위로 일치하며 이름도 레지스트리 표기를 따릅니다. 104는 2026-11-13에 만료되는 임시 등록, 305 Use Proxy는 사용 중단, 306과 418은 (Unused), 510은 OBSOLETED(폐지)로 표시됩니다. nginx 499나 Cloudflare 520–526처럼 특정 제품만 쓰는 코드는 레지스트리에도 목록에도 없습니다.
- 예전 이름으로도 검색됩니다. RFC 9110에서 413은 Content Too Large, 422는 Unprocessable Content로 이름이 바뀌었습니다. 설명에 예전 이름 Payload Too Large와 Unprocessable Entity를 남겨 두었으므로 어느 이름으로 검색해도 찾을 수 있습니다. 418은 만우절 RFC 2324가 ‘I'm a teapot’으로 쓴 탓에 RFC 9110 15.5.19절이 예약해 두었으며, 설명에도 그렇게 적었습니다.
- 설명은 영어로만 나옵니다. 모든 언어 페이지에서 이름과 설명이 영어입니다. 숫자만 입력하면 그 숫자로 시작하는 코드를 찾고(
20이면 200–208) 이름이나 설명 속 숫자는 보지 않습니다. 그 밖의 검색은 이름과 영어 설명의 단어와 일치하는 항목을 찾으므로 ‘리다이렉트’로는 결과가 없고 영어로 검색해야 합니다. 다만redirect로는 307과 308만 나오고, 301과 302의 설명에는moved라는 단어가 쓰였습니다. 전각 숫자와 영문은 검색 전에 반각으로 바꿉니다(NFKC 정규화).
FAQ
HTTP 상태 코드 범위별 의미는 무엇입니까?
1xx=정보(요청 수신, 처리 중), 2xx=성공(요청 완료), 3xx=리다이렉트(추가 조치 필요), 4xx=클라이언트 오류(잘못된 요청, 미인증 등), 5xx=서버 오류(유효한 요청 처리 실패).
301과 302의 차이는 무엇입니까?
301 Moved Permanently는 리소스에 새 영구 URI가 생겼으니 앞으로는 그 주소를 써야 한다는 뜻입니다(RFC 9110 15.4.2절). 302 Found는 일시적인 이동이므로 클라이언트는 앞으로도 원래 URI를 계속 써야 합니다(15.4.3절). Google 크롤러는 301을 리다이렉트 대상을 처리해야 한다는 강한 신호로, 302를 약한 신호로 다룹니다. 두 경우 모두 브라우저가 POST를 GET으로 바꿀 수 있으니, 메서드를 유지하려면 308과 307을 쓰세요.
404와 410의 차이는 무엇입니까?
리소스를 일부러 삭제했고 다시 돌아오지 않을 것을 서버가 알고 있다면 410 Gone을 씁니다. 영구적인지 판단할 수 없을 때는 404를 쓰라고 RFC 9110 15.5.11절에 나와 있습니다. Google 검색에서는 차이가 없습니다. 429를 제외한 4xx는 모두 같은 방식으로 처리되어 URL이 색인에서 제거됩니다.
API에서 429가 중요한 이유는 무엇입니까?
429 Too Many Requests는 요청 한도를 넘었을 때 쓰는 상태 코드입니다(RFC 6585 4절). 응답에 몇 초 기다려야 하는지 Retry-After로 알려 줄 수 있으며, 클라이언트는 최소한 그만큼 기다리고 429가 계속되면 간격을 늘려야 합니다. Google 크롤러는 429를 서버 오류처럼 보고 크롤링 속도를 낮춥니다.
검색한 내용이 어딘가로 전송되나요?
아니요. 64개 코드는 페이지 안에 들어 있고, 검색은 브라우저에서 목록을 거르는 것뿐입니다. 검색어는 전송하지도 저장하지도 않습니다. 통계가 켜져 있으면 검색 이벤트에 도구 이름과 동작 종류만 기록되고, 입력한 검색어는 포함되지 않습니다.