liminfoHTTP Status Codes
HTTP & gRPC 상태 코드 레퍼런스 (HTTP 1xx~5xx + gRPC 0~16)
| 코드 | 이름 | 설명 |
|---|---|---|
| 100 | Continue | 서버가 요청 헤더를 수신했으며 클라이언트가 본문을 보내야 합니다. |
| 101 | Switching Protocols | 서버가 클라이언트의 프로토콜 전환 요청을 수락했습니다. |
| 102 | Processing | 서버가 요청을 수신하여 처리 중이지만 아직 응답이 없습니다. (WebDAV) |
| 103 | Early Hints | 최종 응답 전에 일부 헤더를 미리 반환합니다. |
| 200 | OK | 요청이 성공적으로 처리되었습니다. |
| 201 | Created | 요청이 성공적이었으며 새로운 리소스가 생성되었습니다. |
| 202 | Accepted | 요청이 접수되었지만 아직 처리가 완료되지 않았습니다. |
| 203 | Non-Authoritative Information | 요청이 성공했지만 변환 프록시에서 수정된 정보입니다. |
| 204 | No Content | 요청이 성공했지만 반환할 콘텐츠가 없습니다. |
| 205 | Reset Content | 요청이 성공했으며 클라이언트의 문서 뷰를 리셋해야 합니다. |
| 206 | Partial Content | Range 헤더로 인해 리소스의 일부만 반환되었습니다. |
| 207 | Multi-Status | 여러 리소스에 대한 상태를 포함하는 응답입니다. (WebDAV) |
| 301 | Moved Permanently | 요청한 리소스가 영구적으로 새 URL로 이동했습니다. |
| 302 | Found | 요청한 리소스가 일시적으로 다른 URL에 있습니다. |
| 303 | See Other | 응답을 다른 URL에서 GET으로 가져와야 합니다. |
| 304 | Not Modified | 리소스가 수정되지 않았으므로 캐시된 버전을 사용합니다. |
| 307 | Temporary Redirect | 요청한 리소스가 일시적으로 다른 URL에 있으며, 같은 메서드를 사용합니다. |
| 308 | Permanent Redirect | 요청한 리소스가 영구적으로 다른 URL에 있으며, 같은 메서드를 사용합니다. |
| 400 | Bad Request | 잘못된 요청 구문이나 유효하지 않은 요청입니다. |
| 401 | Unauthorized | 인증이 필요합니다. 유효한 인증 자격 증명을 제공하세요. |
| 402 | Payment Required | 결제가 필요합니다. (향후 사용을 위해 예약됨) |
| 403 | Forbidden | 서버가 요청을 이해했지만 권한이 없어 거부합니다. |
| 404 | Not Found | 요청한 리소스를 찾을 수 없습니다. |
| 405 | Method Not Allowed | 요청한 HTTP 메서드가 허용되지 않습니다. |
| 406 | Not Acceptable | 요청한 리소스가 Accept 헤더 조건을 만족하지 않습니다. |
| 407 | Proxy Authentication Required | 프록시 인증이 필요합니다. |
| 408 | Request Timeout | 서버가 요청을 기다리다가 시간이 초과되었습니다. |
| 409 | Conflict | 요청이 현재 서버의 상태와 충돌합니다. |
| 410 | Gone | 요청한 리소스가 영구적으로 삭제되었습니다. |
| 411 | Length Required | Content-Length 헤더가 필요합니다. |
| 412 | Precondition Failed | 요청 헤더의 전제 조건이 서버에서 충족되지 않았습니다. |
| 413 | Payload Too Large | 요청 본문이 서버가 처리할 수 있는 크기를 초과합니다. |
| 414 | URI Too Long | 요청 URI가 서버가 처리할 수 있는 길이를 초과합니다. |
| 415 | Unsupported Media Type | 요청의 미디어 타입을 서버가 지원하지 않습니다. |
| 416 | Range Not Satisfiable | 요청한 Range를 서버가 제공할 수 없습니다. |
| 418 | I'm a Teapot | 서버는 찻주전자이므로 커피를 내릴 수 없습니다. (RFC 2324) |
| 422 | Unprocessable Entity | 요청은 올바르나 의미상 처리할 수 없습니다. (WebDAV) |
| 429 | Too Many Requests | 클라이언트가 일정 시간 동안 너무 많은 요청을 보냈습니다. |
| 431 | Request Header Fields Too Large | 요청 헤더 필드가 너무 큽니다. |
| 451 | Unavailable For Legal Reasons | 법적인 이유로 접근이 차단되었습니다. |
| 500 | Internal Server Error | 서버 내부 오류가 발생했습니다. |
| 501 | Not Implemented | 서버가 요청 메서드를 지원하지 않습니다. |
| 502 | Bad Gateway | 게이트웨이/프록시가 상위 서버로부터 잘못된 응답을 받았습니다. |
| 503 | Service Unavailable | 서버가 일시적으로 요청을 처리할 수 없습니다. (과부하/점검) |
| 504 | Gateway Timeout | 게이트웨이/프록시가 상위 서버로부터 응답을 받지 못했습니다. |
| 505 | HTTP Version Not Supported | 요청에 사용된 HTTP 버전을 서버가 지원하지 않습니다. |
| 507 | Insufficient Storage | 서버에 요청을 저장할 공간이 부족합니다. (WebDAV) |
| 511 | Network Authentication Required | 네트워크 인증이 필요합니다. (캡티브 포탈) |
HTTP Status Codes 소개
HTTP & gRPC 상태 코드 레퍼런스는 두 가지 주요 프로토콜 상태 코드 시스템을 대화형으로 조회할 수 있는 도구입니다. HTTP 탭에서는 RFC 7231, RFC 6585, RFC 4918(WebDAV) 등에 정의된 45개 이상의 표준 HTTP 응답 상태 코드를 1xx 정보, 2xx 성공, 3xx 리다이렉션, 4xx 클라이언트 오류, 5xx 서버 오류 5개 카테고리로 분류하여 제공합니다.
gRPC 탭에서는 gRPC 사양에 정의된 17개의 정규 gRPC 상태 코드(0 OK ~ 16 UNAUTHENTICATED)를 모두 다룹니다. 각 gRPC 코드 항목은 숫자 코드, 정규 이름, 설명, HTTP 동등 매핑, 사용 시점 안내, 실용적인 예시 시나리오를 표시합니다. gRPC 코드를 클릭하면 상세 정보가 펼쳐집니다.
백엔드 개발자, API 엔지니어, 마이크로서비스 아키텍트, DevOps 전문가가 REST/HTTP와 gRPC API를 모두 다룰 때 유용하도록 설계되었습니다. gRPC와 HTTP 상태 코드 간의 매핑을 명확히 하여 혼합 프로토콜 시스템에서 일관된 오류 처리를 설계하는 데 도움을 줍니다.
주요 기능
- HTTP 상태 코드와 gRPC 상태 코드를 하나의 통합 도구에서 두 탭으로 제공
- 100부터 511까지 45개 이상의 HTTP 상태 코드를 색상 구분 카테고리 배지와 함께 전체 수록
- 17개 gRPC 상태 코드 전체 수록 (OK, CANCELLED, UNKNOWN, INVALID_ARGUMENT, DEADLINE_EXCEEDED, NOT_FOUND, ALREADY_EXISTS, PERMISSION_DENIED, RESOURCE_EXHAUSTED, FAILED_PRECONDITION, ABORTED, OUT_OF_RANGE, UNIMPLEMENTED, INTERNAL, UNAVAILABLE, DATA_LOSS, UNAUTHENTICATED)
- 각 gRPC 코드에 대응하는 HTTP 상태 코드를 보여주는 gRPC-to-HTTP 매핑
- 각 gRPC 코드의 "사용 시점" 안내와 실용적 예시 시나리오를 펼쳐볼 수 있는 상세 카드
- HTTP와 gRPC 탭 모두에서 코드 번호, 이름, 설명을 대상으로 한 실시간 검색 필터링
- HTTP 카테고리 필터: 전체, 1xx 정보, 2xx 성공, 3xx 리다이렉션, 4xx 클라이언트 오류, 5xx 서버 오류
- 한국어/영어 양방향 인터페이스로 모든 설명을 두 언어로 제공
자주 묻는 질문
HTTP 상태 코드와 gRPC 상태 코드의 차이점은 무엇인가요?
HTTP 상태 코드는 HTTP 응답에서 요청 결과를 나타내는 3자리 숫자 코드(100-599)로, 1xx 정보, 2xx 성공, 3xx 리다이렉션, 4xx 클라이언트 오류, 5xx 서버 오류의 5개 카테고리로 구성됩니다. gRPC 상태 코드는 gRPC(Google Remote Procedure Call) 통신에서 사용되는 별도의 17개 코드(0-16) 집합입니다. 각 gRPC 코드에는 대응하는 HTTP 동등 코드가 있지만, 매핑이 항상 일대일은 아닙니다. 예를 들어 gRPC의 FAILED_PRECONDITION, INVALID_ARGUMENT, OUT_OF_RANGE는 모두 HTTP 400에 매핑됩니다.
gRPC 상태 코드는 HTTP 상태 코드에 어떻게 매핑되나요?
공식 gRPC-to-HTTP 매핑은 다음과 같습니다: OK→200, CANCELLED→499, UNKNOWN→500, INVALID_ARGUMENT→400, DEADLINE_EXCEEDED→504, NOT_FOUND→404, ALREADY_EXISTS→409, PERMISSION_DENIED→403, RESOURCE_EXHAUSTED→429, FAILED_PRECONDITION→400, ABORTED→409, OUT_OF_RANGE→400, UNIMPLEMENTED→501, INTERNAL→500, UNAVAILABLE→503, DATA_LOSS→500, UNAUTHENTICATED→401. 이 매핑은 gRPC-Gateway 등 HTTP/gRPC 브리징 도구에서 사용됩니다.
gRPC에서 INVALID_ARGUMENT, FAILED_PRECONDITION, OUT_OF_RANGE의 차이는?
세 코드 모두 HTTP 400에 매핑되지만 의미가 다릅니다. INVALID_ARGUMENT(3)는 시스템 상태와 무관하게 인수가 잘못된 경우(예: 형식 오류 이메일), FAILED_PRECONDITION(9)은 시스템이 필요한 상태가 아닌 경우(예: 비어 있지 않은 디렉토리 삭제), OUT_OF_RANGE(11)는 값이 유효 범위를 벗어난 경우(예: 전체 페이지 수를 초과한 페이지 번호)에 사용합니다.
gRPC에서 PERMISSION_DENIED와 UNAUTHENTICATED의 차이는?
UNAUTHENTICATED(16, HTTP 401 매핑)는 유효한 인증 자격 증명이 없음을 의미합니다 — 호출자가 자신을 식별하지 않았습니다. PERMISSION_DENIED(7, HTTP 403 매핑)는 호출자가 인증되었지만 해당 작업에 대한 충분한 권한이 없음을 나타냅니다. 간단히 말해 UNAUTHENTICATED는 "당신은 누구인가요?"이고 PERMISSION_DENIED는 "누구인지 알지만 이 작업을 할 수 없습니다"입니다.
gRPC에서 ABORTED와 ALREADY_EXISTS는 언제 각각 사용하나요?
둘 다 HTTP 409(Conflict)에 매핑되지만 용도가 다릅니다. ALREADY_EXISTS(6)는 이미 존재하는 리소스를 생성하려 할 때(예: 중복 사용자명 등록) 사용합니다. ABORTED(10)는 트랜잭션 충돌이나 경쟁 상태로 인해 작업이 중단된 동시성 충돌에 사용하며, 클라이언트가 전체 read-modify-write 시퀀스를 재시도할 수 있습니다.
gRPC UNAVAILABLE은 무엇이며 언제 사용하나요?
UNAVAILABLE(14, HTTP 503 매핑)은 서비스가 일시적으로 사용 불가함을 나타냅니다. 버그나 불변 조건 위반을 나타내는 INTERNAL(13)과 달리, UNAVAILABLE은 지수 백오프로 재시도하면 해결될 수 있는 일시적 상태를 의미합니다. 점검 기간, 일시적 과부하, 네트워크 연결 문제에 사용하세요. 클라이언트는 이를 재시도 신호로 처리해야 합니다.
검색 및 탭 기능은 어떻게 사용하나요?
HTTP 또는 gRPC 탭을 클릭하여 두 상태 코드 시스템 간에 전환합니다. 검색창에 텍스트를 입력하면 코드 번호, 이름, 설명을 기준으로 필터링됩니다. HTTP 코드에서는 카테고리 버튼(전체, 1xx, 2xx, 3xx, 4xx, 5xx)으로 범위별 필터링이 가능합니다. gRPC 코드에서는 코드 카드를 클릭하면 사용 시점과 예시 시나리오를 보여주는 상세 정보가 펼쳐집니다. 검색은 각 탭에서 독립적으로 작동합니다.
502 Bad Gateway나 504 Gateway Timeout 오류의 원인은 무엇인가요?
502 Bad Gateway는 게이트웨이나 프록시 서버가 상위 서버로부터 잘못된 응답을 받았을 때 발생합니다. 504 Gateway Timeout은 게이트웨이가 상위 서버로부터 적시에 응답을 받지 못했을 때 발생합니다. gRPC에서는 DEADLINE_EXCEEDED(4)가 504에 해당하고, INTERNAL(13) 또는 UNAVAILABLE(14)이 502 상황에 대응할 수 있습니다.