|
400
|
Bad Request
RFC 9110
|
요청 문법, 파라미터, 헤더 등이 잘못되어 서버가 처리할 수 없다는 뜻입니다. |
잘못된 JSON, 누락된 필수 값, 깨진 URL, 비정상 헤더에서 자주 발생합니다. |
요청 본문 형식, Content-Type, 쿼리 파라미터, 서버 검증 로그를 확인합니다.
관련: 422
|
|
401
|
Unauthorized
RFC 9110
|
인증이 필요하거나 인증 정보가 유효하지 않다는 뜻입니다. |
로그인 토큰 누락, 만료된 API 키, 잘못된 Authorization 헤더에서 사용됩니다. |
WWW-Authenticate 헤더, 토큰 만료 시간, 인증 스킴, 쿠키 전달 여부를 확인합니다.
관련: 403, 407
|
|
402
|
Payment Required
RFC 9110
|
결제가 필요하다는 목적으로 예약된 코드지만 표준 의미는 널리 정착되지 않았습니다. |
일부 API나 결제 서비스에서 결제, 크레딧, 구독 문제를 표현하기 위해 비공식적으로 사용할 수 있습니다. |
서비스별 API 문서에서 402의 실제 의미와 복구 방법을 확인합니다.
관련: 403, 429
|
|
403
|
Forbidden
RFC 9110
|
서버가 요청을 이해했지만 접근을 허용하지 않는다는 뜻입니다. |
권한 부족, IP 차단, 관리자 정책, 비공개 리소스 접근에서 자주 발생합니다. |
인증 여부와 별개로 권한 정책, ACL, WAF, 파일 권한, 라우팅 규칙을 확인합니다.
관련: 401, 404, 451
|
|
404
|
Not Found
RFC 9110
|
요청한 리소스를 찾을 수 없거나 존재 여부를 공개하지 않는다는 뜻입니다. |
URL 오타, 삭제된 페이지, 잘못된 라우트, 숨김 처리된 리소스에서 가장 흔하게 보입니다. |
내부 링크, sitemap, 리다이렉션, 라우팅 테이블, 삭제된 콘텐츠의 대체 URL을 확인합니다.
관련: 410, 403, 451
|
|
405
|
Method Not Allowed
RFC 9110
|
리소스는 있지만 요청한 HTTP 메서드는 허용되지 않는다는 뜻입니다. |
GET만 가능한 URL에 POST를 보내거나 API 라우트의 메서드 설정이 맞지 않을 때 발생합니다. |
Allow 헤더, 라우터 메서드 정의, 프록시의 메서드 제한 정책을 확인합니다.
관련: 404, 501
|
|
406
|
Not Acceptable
RFC 9110
|
클라이언트가 Accept 헤더로 요구한 표현을 서버가 제공할 수 없다는 뜻입니다. |
지원하지 않는 미디어 타입, 언어, 인코딩만 요청했을 때 발생할 수 있습니다. |
Accept, Accept-Language, Accept-Encoding 헤더와 서버의 콘텐츠 협상 설정을 확인합니다.
관련: 415
|
|
407
|
Proxy Authentication Required
RFC 9110
|
프록시를 사용하려면 인증이 필요하다는 뜻입니다. |
회사망, 보안 프록시, 게이트웨이 인증 환경에서 볼 수 있습니다. |
Proxy-Authenticate, Proxy-Authorization 헤더와 네트워크 프록시 설정을 확인합니다.
관련: 401, 305
|
|
408
|
Request Timeout
RFC 9110
|
서버가 기다리는 시간 안에 클라이언트 요청을 완전히 받지 못했다는 뜻입니다. |
느린 네트워크, 큰 업로드, 연결 유지 시간 초과, 로드밸런서 타임아웃에서 발생할 수 있습니다. |
클라이언트 재시도, 업로드 크기, keep-alive 설정, 프록시 타임아웃 값을 확인합니다.
관련: 504
|
|
409
|
Conflict
RFC 9110
|
요청이 현재 리소스 상태와 충돌해 처리할 수 없다는 뜻입니다. |
중복 생성, 버전 충돌, 동시 수정, 상태 전이 불일치에서 자주 사용됩니다. |
리소스 버전, ETag, 중복 키, 비즈니스 상태 전이 규칙을 확인합니다.
관련: 412, 422
|
|
410
|
Gone
RFC 9110
|
리소스가 과거에는 있었지만 지금은 영구적으로 제거되었다는 뜻입니다. |
삭제된 페이지를 검색엔진과 클라이언트에 명확히 알리고 싶을 때 404보다 구체적입니다. |
대체 URL이 있으면 301을, 영구 삭제가 맞으면 410과 sitemap 정리를 함께 검토합니다.
관련: 404, 301
|
|
411
|
Length Required
RFC 9110
|
서버가 Content-Length 없는 요청을 거부한다는 뜻입니다. |
일부 서버나 게이트웨이가 본문 길이를 미리 알아야 하는 요청에서 발생할 수 있습니다. |
Content-Length, Transfer-Encoding, 클라이언트 라이브러리의 스트리밍 전송 방식을 확인합니다.
관련: 413
|
|
412
|
Precondition Failed
RFC 9110
|
If-Match 같은 조건부 요청의 전제 조건이 실패했다는 뜻입니다. |
동시 수정 방지, 캐시 재검증, ETag 기반 업데이트에서 사용됩니다. |
If-Match, If-None-Match, If-Unmodified-Since와 현재 리소스 버전을 비교합니다.
관련: 304, 409, 428
|
|
413
|
Content Too Large
RFC 9110
|
요청 본문이 서버가 허용하는 크기보다 크다는 뜻입니다. |
파일 업로드 제한, JSON 본문 크기 제한, 프록시 body size 제한에서 자주 발생합니다. |
서버, 프록시, CDN, 애플리케이션의 업로드 제한 값을 함께 확인합니다.
관련: 411, 431
|
|
414
|
URI Too Long
RFC 9110
|
요청 URI가 서버가 처리할 수 있는 길이를 넘었다는 뜻입니다. |
매우 긴 쿼리 문자열, 잘못된 리다이렉션 루프, GET에 과도한 데이터를 넣은 경우 발생합니다. |
긴 데이터는 POST 본문으로 옮기고 프록시/서버의 URI 길이 제한을 확인합니다.
관련: 400, 431
|
|
415
|
Unsupported Media Type
RFC 9110
|
요청 본문의 미디어 타입을 서버가 지원하지 않는다는 뜻입니다. |
JSON API에 잘못된 Content-Type을 보내거나 지원하지 않는 파일 형식을 업로드할 때 발생합니다. |
Content-Type, 파일 확장자, multipart 설정, 서버 파서 등록 여부를 확인합니다.
관련: 406, 422
|
|
416
|
Range Not Satisfiable
RFC 9110
|
요청한 Range가 리소스 크기와 맞지 않아 제공할 수 없다는 뜻입니다. |
다운로드 이어받기나 스트리밍에서 범위 값이 파일 크기를 벗어날 때 발생합니다. |
Range 헤더, Content-Range, 파일 크기, 캐시된 메타데이터 불일치를 확인합니다.
관련: 206
|
|
417
|
Expectation Failed
RFC 9110
|
Expect 헤더의 조건을 서버가 만족할 수 없다는 뜻입니다. |
Expect: 100-continue 같은 기대 조건을 서버나 프록시가 지원하지 않을 때 발생할 수 있습니다. |
Expect 헤더를 제거하거나 서버의 100 Continue 처리 지원 여부를 확인합니다.
관련: 100
|
|
418
|
I'm a teapot
RFC 2324 / RFC 9110
|
만우절 RFC에서 유래한 코드로, 실제 오류 처리보다는 역사적·문화적 의미가 큽니다. |
일부 서비스가 장난성 응답, 테스트, 개발자 문화 표현으로 사용하지만 일반 API 설계에는 권장되지 않습니다. |
운영 API에서는 명확한 의미의 4xx/5xx 코드를 사용하는 것이 좋습니다.
관련: 400
|
|
421
|
Misdirected Request
RFC 9110
|
요청이 해당 응답을 만들 수 없는 서버로 잘못 전달되었다는 뜻입니다. |
HTTP/2 연결 재사용, TLS/SNI, CDN, 리버스 프록시 설정이 어긋날 때 발생할 수 있습니다. |
Host, SNI, 인증서, HTTP/2 connection coalescing, CDN 오리진 라우팅을 확인합니다.
관련: 400, 502
|
|
422
|
Unprocessable Content
RFC 9110
|
요청 문법은 맞지만 의미상 처리할 수 없는 내용이라는 뜻입니다. |
API 유효성 검사 실패, 비즈니스 규칙 위반, 필드 값 오류를 표현할 때 자주 사용됩니다. |
400은 형식 오류, 422는 의미·검증 오류로 구분할지 API 규칙을 정합니다.
관련: 400, 409, 415
|
|
423
|
Locked
RFC 4918
|
대상 리소스가 잠겨 있어 요청을 처리할 수 없다는 WebDAV 상태 코드입니다. |
파일 편집 잠금, 협업 문서, WebDAV 리소스 잠금에서 사용됩니다. |
잠금 소유자, 잠금 만료, 해제 API, 충돌 처리 정책을 확인합니다.
관련: 409, 424
|
|
424
|
Failed Dependency
RFC 4918
|
이전 작업 실패 때문에 현재 요청도 수행할 수 없다는 WebDAV 상태 코드입니다. |
여러 작업이 의존 관계를 가질 때 앞선 작업 실패가 뒤 작업 실패로 이어지는 경우 사용됩니다. |
실패한 선행 작업과 현재 작업의 의존 관계를 응답 본문에 명확히 제공합니다.
관련: 207, 423
|
|
425
|
Too Early
RFC 8470
|
서버가 재전송 위험이 있는 너무 이른 요청을 처리하지 않겠다는 뜻입니다. |
TLS 1.3 0-RTT early data처럼 재생 공격 위험이 있는 요청에서 사용될 수 있습니다. |
멱등성이 없는 요청을 0-RTT로 보내지 않도록 클라이언트와 서버 설정을 확인합니다.
관련: 429, 503
|
|
426
|
Upgrade Required
RFC 9110
|
서버가 현재 프로토콜로는 요청을 처리하지 않고 업그레이드를 요구한다는 뜻입니다. |
HTTP 버전, TLS, WebSocket 등 특정 프로토콜 업그레이드가 필요한 경우 사용됩니다. |
Upgrade 헤더, 지원 프로토콜, 프록시의 업그레이드 전달 여부를 확인합니다.
관련: 101
|
|
428
|
Precondition Required
RFC 6585
|
서버가 조건부 요청 헤더를 요구한다는 뜻입니다. |
동시 수정으로 인한 lost update를 막기 위해 If-Match 같은 조건을 강제할 때 사용됩니다. |
클라이언트가 ETag를 읽고 If-Match로 업데이트하도록 API 문서와 오류 메시지를 제공합니다.
관련: 412, 409
|
|
429
|
Too Many Requests
RFC 6585
|
클라이언트가 일정 시간 동안 너무 많은 요청을 보냈다는 뜻입니다. |
API rate limit, 로그인 시도 제한, 봇 차단, 과도한 새로고침에서 자주 발생합니다. |
Retry-After, rate limit 헤더, 사용자별/토큰별 제한 단위, 백오프 전략을 확인합니다.
관련: 403, 503
|
|
431
|
Request Header Fields Too Large
RFC 6585
|
요청 헤더 전체 또는 특정 헤더 필드가 너무 크다는 뜻입니다. |
쿠키가 과도하게 커졌거나 인증 토큰, 추적 헤더, 프록시 추가 헤더가 누적될 때 발생합니다. |
Cookie 크기, Authorization 헤더, 프록시 체인에서 추가되는 헤더 크기를 줄입니다.
관련: 400, 413, 414
|
|
451
|
Unavailable For Legal Reasons
RFC 7725
|
법적 사유로 리소스 접근을 제공할 수 없다는 뜻입니다. |
법원 명령, 정부 요청, 저작권 신고, 지역별 법규 등 법적 요구로 콘텐츠 접근을 제한할 때 사용됩니다. |
403이나 404와 달리 차단 이유가 법적 요구임을 투명하게 알리는 코드인지 확인합니다.
관련: 403, 404, 410
|