HTTP 상태 코드

모든 HTTP 상태 코드의 완전한 레퍼런스(설명 및 예제 포함).

61개 중 61개 표시

1xx 정보

4개의 상태 코드

100

계속

서버가 요청 헤더를 수신했으며 클라이언트는 요청 본문 전송을 계속해야 합니다. 이는 전체 페이로드를 전송하기 전에 서버가 요청을 수락할지 클라이언트가 확인할 수 있게 하여 대용량 업로드를 최적화하는 데 사용됩니다.

일반적인 사용 사례: 클라이언트가 대용량 요청 본문을 업로드하기 전에 Expect: 100-continue 헤더를 보낼 때 사용되며, 서버가 대역폭을 낭비하지 않고 조기에 요청을 거부할 수 있게 합니다.

RFC 9110
101

프로토콜 전환

서버가 클라이언트의 Upgrade 헤더 요청에 따라 다른 프로토콜로 전환하고 있습니다. 서버가 동의하며 이 응답 후에 새로운 프로토콜로 통신합니다.

일반적인 사용 사례: HTTP 연결을 WebSocket 연결로 업그레이드할 때 가장 흔히 볼 수 있습니다. 클라이언트가 Upgrade: websocket 헤더를 보내면 서버가 101로 응답하여 전환을 확인합니다.

RFC 9110
102

처리 중

서버가 요청을 수신하여 처리하고 있지만 아직 응답을 사용할 수 없습니다. 서버가 장시간 실행되는 작업을 처리하는 동안 클라이언트가 시간 초과되는 것을 방지합니다.

일반적인 사용 사례: 완료까지 오래 걸릴 수 있는 WebDAV 작업에 사용됩니다. 서버가 연결을 끊지 않았으며 여전히 요청을 처리하고 있음을 클라이언트에 알립니다.

RFC 2518
103

조기 힌트

서버가 최종 응답 전에 예비 응답 헤더를 보냅니다. 이를 통해 서버가 아직 전체 응답을 준비하는 동안 클라이언트가 리소스 사전 로딩을 시작할 수 있습니다.

일반적인 사용 사례: Link 헤더를 조기에 전송하여 브라우저가 최종 HTML 응답이 도착하기 전에 CSS, JavaScript 또는 폰트를 사전 로딩할 수 있게 하여 페이지 로드 성능을 향상시킵니다.

RFC 8297

2xx 성공

10개의 상태 코드

200

성공

요청이 성공했습니다. 성공의 의미는 HTTP 메서드에 따라 다릅니다: GET은 요청된 리소스를 반환하고, POST는 작업의 결과를 반환합니다.

일반적인 사용 사례: 대부분의 API 호출에 대한 표준 성공 응답입니다. GET 요청이 데이터를 반환하거나, PUT 요청이 리소스를 업데이트하거나, 작업이 응답 본문과 함께 성공적으로 완료될 때 사용됩니다.

RFC 9110
요청
GET /api/users/42 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
응답
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "name": "Jane Doe",
  "email": "jane@example.com",
  "created_at": "2025-08-15T10:30:00Z"
}
201

생성됨

요청이 충족되었으며 새 리소스가 생성되었습니다. 응답에는 일반적으로 새로 생성된 리소스를 가리키는 Location 헤더가 포함됩니다.

일반적인 사용 사례: 새 리소스를 생성하는 성공적인 POST 요청 후에 반환됩니다. 예를 들어 새 사용자 계정 생성, 블로그 게시물 추가 또는 파일 업로드 등입니다.

RFC 9110
요청
POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "Jane Doe",
  "email": "jane@example.com"
}
응답
HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/users/42

{
  "id": 42,
  "name": "Jane Doe",
  "email": "jane@example.com",
  "created_at": "2025-08-15T10:30:00Z"
}
202

수락됨

요청이 처리를 위해 수락되었지만 처리가 완료되지 않았습니다. 요청이 최종적으로 실행될 수도 있고 실행되지 않을 수도 있으며, 실제 처리 시 거부될 수 있습니다.

일반적인 사용 사례: 서버가 나중에 처리하기 위해 작업을 대기열에 넣는 비동기 작업에 사용됩니다. 예를 들어 이메일 전송, 보고서 생성 또는 배치 작업 트리거 등입니다.

RFC 9110
203

비신뢰적 정보

요청은 성공했지만 헤더에 반환된 메타데이터가 원본 서버가 아닌 로컬 또는 타사 복사본에서 가져온 것일 수 있습니다. 포함된 페이로드는 원본 서버의 200 응답의 수정된 버전입니다.

일반적인 사용 사례: 실제로는 거의 사용되지 않습니다. 변환 프록시가 원본 서버의 응답 헤더를 수정할 때 나타날 수 있으며, 메타데이터가 원본과 일치하지 않을 수 있음을 나타냅니다.

RFC 9110
204

콘텐츠 없음

서버가 요청을 성공적으로 처리했으며 응답 페이로드 본문에 보낼 추가 콘텐츠가 없습니다. 응답에는 업데이트된 헤더가 포함될 수 있습니다.

일반적인 사용 사례: 성공적인 DELETE 요청 후 또는 응답 본문이 필요 없는 PUT/PATCH 업데이트 후에 반환됩니다. 확인만으로 충분한 실행 후 잊기(fire-and-forget) 작업에도 사용됩니다.

RFC 9110
요청
DELETE /api/users/42 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
응답
HTTP/1.1 204 No Content
205

콘텐츠 재설정

서버가 요청을 처리했으며 요청 전송을 유발한 문서 뷰를 사용자 에이전트가 재설정하기를 원합니다. 응답 본문은 포함되지 않습니다.

일반적인 사용 사례: 요청을 제출한 양식이나 UI를 재설정하도록 클라이언트에 알리는 데 사용됩니다. 예를 들어 양식을 성공적으로 제출한 후 서버가 브라우저에 양식 필드를 지우도록 신호를 보낼 수 있습니다.

RFC 9110
206

부분 콘텐츠

클라이언트가 보낸 Range 헤더로 인해 서버가 리소스의 일부만 전달하고 있습니다. 이는 재개 가능한 다운로드와 미디어 스트리밍에 사용됩니다.

일반적인 사용 사례: 클라이언트가 큰 파일의 특정 바이트 범위를 요청할 때 사용되며, 재개 가능한 다운로드, 비디오 탐색 및 병렬 청크 다운로드와 같은 기능을 가능하게 합니다.

RFC 9110
207

다중 상태

여러 상태 코드가 적절할 수 있는 상황에서 여러 리소스에 대한 정보를 전달하는 WebDAV 응답입니다. 응답 본문은 각 하위 요청에 대한 개별 상태 코드를 포함하는 XML 문서입니다.

일반적인 사용 사례: 각 하위 작업이 다른 결과를 가질 수 있는 WebDAV 일괄 작업에 사용됩니다. 예를 들어 여러 파일을 복사할 때 일부는 성공하고 일부는 실패하는 경우입니다.

RFC 4918
208

이미 보고됨

DAV: propstat 응답 요소 내에서 동일 컬렉션에 대한 여러 바인딩의 내부 멤버를 반복적으로 열거하는 것을 방지하기 위해 사용됩니다.

일반적인 사용 사례: 바인딩으로 인해 컬렉션 내 여러 위치에 나타나는 동일 리소스를 여러 번 나열하는 것을 방지하는 데 사용되는 WebDAV 상태입니다.

RFC 5842
226

IM 사용됨

서버가 리소스에 대한 GET 요청을 처리했으며, 응답은 현재 인스턴스에 적용된 하나 이상의 인스턴스 조작 결과의 표현입니다.

일반적인 사용 사례: 델타 인코딩과 함께 사용되어 리소스의 현재 버전과 이전에 캐시된 버전 간의 변경 사항(델타)만 전송하여 대역폭 사용량을 줄입니다.

RFC 3229

3xx 리다이렉션

7개의 상태 코드

300

다중 선택

대상 리소스에 둘 이상의 표현이 있으며 사용자 또는 사용자 에이전트가 선호하는 것을 선택할 수 있습니다. 서버는 사용 가능한 표현 목록을 포함할 수 있습니다.

일반적인 사용 사례: 실제로는 거의 사용되지 않습니다. 리소스가 여러 형식(예: JSON, XML, HTML)으로 사용 가능하고 서버가 클라이언트에게 명시적으로 선택하게 하려는 경우에 사용될 수 있습니다.

RFC 9110
301

영구 이동

대상 리소스에 새로운 영구 URI가 할당되었으며 이 리소스에 대한 향후 모든 참조는 반환된 Location URI를 사용해야 합니다. 검색 엔진은 인덱스를 업데이트합니다.

일반적인 사용 사례: 페이지 또는 API 엔드포인트가 새 URL로 영구적으로 이동한 경우 사용됩니다. 웹사이트 재구성, 도메인 이름 변경 또는 이전 URL 패턴 폐기 시 SEO에 필수적입니다.

RFC 9110
요청
GET /old-page HTTP/1.1
Host: www.example.com
응답
HTTP/1.1 301 Moved Permanently
Location: https://www.example.com/new-page
Content-Type: text/html

<html><body>This page has moved to <a href="https://www.example.com/new-page">/new-page</a>.</body></html>
302

발견됨

대상 리소스가 일시적으로 다른 URI에 있습니다. 리다이렉션이 때때로 변경될 수 있으므로 클라이언트는 향후 요청에 원래 URI를 계속 사용해야 합니다.

일반적인 사용 사례: 로그인 페이지로의 리다이렉트, 유지보수 페이지로 사용자 보내기 또는 다양한 페이지 버전의 A/B 테스트와 같은 임시 리다이렉트에 사용됩니다.

RFC 9110
요청
GET /dashboard HTTP/1.1
Host: www.example.com
응답
HTTP/1.1 302 Found
Location: https://www.example.com/login?redirect=/dashboard
303

기타 참조

서버가 일반적으로 POST 작업 후에 GET 요청을 사용하여 사용자 에이전트를 다른 리소스로 리다이렉트하고 있습니다. 이를 통해 클라이언트가 양식 데이터를 다시 제출하지 않도록 합니다.

일반적인 사용 사례: POST 양식 제출 후 확인 페이지로 리다이렉트하는 데 사용됩니다(Post/Redirect/Get 패턴). 사용자가 페이지를 새로고침할 때 양식이 중복 제출되는 것을 방지합니다.

RFC 9110
304

수정되지 않음

요청 헤더 If-Modified-Since 또는 If-None-Match에 지정된 버전 이후로 리소스가 수정되지 않았습니다. 서버는 리소스 본문을 다시 보낼 필요가 없습니다.

일반적인 사용 사례: 클라이언트가 조건부 요청을 하고 리소스가 변경되지 않았을 때 반환되어 클라이언트가 캐시된 복사본을 사용할 수 있게 합니다. 대역폭을 절약하고 로드 시간을 개선합니다.

RFC 9110
요청
GET /api/users/42 HTTP/1.1
Host: api.example.com
If-None-Match: "etag-abc123"
응답
HTTP/1.1 304 Not Modified
ETag: "etag-abc123"
Cache-Control: max-age=3600
307

임시 리다이렉트

대상 리소스가 일시적으로 다른 URI에 있으며 사용자 에이전트는 리다이렉트를 따를 때 요청 메서드를 변경해서는 안 됩니다. 302와 달리 메서드와 본문이 동일하게 유지됩니다.

일반적인 사용 사례: HTTP 메서드를 엄격하게 보존하는 임시 리다이렉트가 필요할 때 사용됩니다. 예를 들어 POST 요청을 GET으로 변경하지 않고 다른 엔드포인트로 리다이렉트하는 경우입니다.

RFC 9110
308

영구 리다이렉트

대상 리소스에 새로운 영구 URI가 할당되었습니다. 301과 유사하지만 리다이렉트를 따를 때 요청 메서드와 본문이 변경되어서는 안 됩니다.

일반적인 사용 사례: HTTP 메서드를 보존해야 하는 영구 리다이렉트에 사용됩니다. 예를 들어 클라이언트가 계속 POST 요청을 보내도록 보장하면서 POST 엔드포인트를 영구적으로 리다이렉트하는 경우입니다.

RFC 9110

4xx 클라이언트 오류

29개의 상태 코드

400

잘못된 요청

잘못된 요청 구문, 유효하지 않은 요청 프레이밍 또는 기만적인 요청 라우팅 등 클라이언트 오류로 인식되는 것으로 인해 서버가 요청을 처리할 수 없거나 처리하지 않습니다.

일반적인 사용 사례: 요청 본문이 잘못된 JSON이거나, 필수 필드가 누락되었거나, 쿼리 매개변수가 유효하지 않거나, 요청이 예상 형식을 준수하지 않을 때 반환됩니다.

RFC 9110
요청
POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "",
  "email": "not-an-email"
}
응답
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "validation_error",
  "message": "Request validation failed",
  "details": [
    { "field": "name", "message": "Name is required" },
    { "field": "email", "message": "Must be a valid email address" }
  ]
}
401

인증되지 않음

대상 리소스에 대한 유효한 인증 자격 증명이 없어 요청이 적용되지 않았습니다. 응답에는 적용 가능한 인증 체계를 나타내는 WWW-Authenticate 헤더가 포함되어야 합니다.

일반적인 사용 사례: 요청에 인증 자격 증명이 없거나 제공된 토큰/자격 증명이 만료되었거나 유효하지 않을 때 반환됩니다. 클라이언트는 재시도 전에 인증해야 합니다.

RFC 9110
요청
GET /api/users/me HTTP/1.1
Host: api.example.com
응답
HTTP/1.1 401 Unauthorized
Content-Type: application/json
WWW-Authenticate: Bearer

{
  "error": "unauthorized",
  "message": "Authentication required. Please provide a valid Bearer token."
}
402

결제 필요

향후 사용을 위해 예약되어 있습니다. 원래 디지털 결제 체계를 위한 것이었으나 이 상태 코드는 널리 표준화되지 않았지만 결제가 필요함을 나타내기 위해 일부 API에서 사용됩니다.

일반적인 사용 사례: 공식적으로는 예약되어 있지만, 일부 API에서는 유료 기능이나 구독이 필요하거나 사용자가 무료 등급 사용 한도를 초과했음을 나타내는 데 사용합니다.

RFC 9110
403

금지됨

서버가 요청을 이해했지만 승인을 거부합니다. 401과 달리 인증이 도움이 되지 않습니다. 클라이언트에게 리소스에 대한 필요한 권한이 없습니다.

일반적인 사용 사례: 사용자가 인증되었지만 필요한 권한이 없을 때 반환됩니다. 예를 들어 일반 사용자가 관리자 전용 엔드포인트에 접근하려 하거나 다른 사용자가 소유한 리소스에 접근하는 경우입니다.

RFC 9110
요청
DELETE /api/users/99 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
응답
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "forbidden",
  "message": "You do not have permission to delete this user. Admin role required."
}
404

찾을 수 없음

원본 서버가 대상 리소스의 현재 표현을 찾지 못했거나 그 존재를 공개하지 않으려 합니다. 이는 일시적이거나 영구적일 수 있습니다.

일반적인 사용 사례: 가장 흔하게 발생하는 오류입니다. 요청된 리소스가 존재하지 않을 때 반환됩니다. 예를 들어 데이터베이스에 없는 ID로 사용자를 요청하거나 일치하는 라우트가 없는 URL에 접근하는 경우입니다.

RFC 9110
요청
GET /api/users/99999 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
응답
HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "not_found",
  "message": "User with ID 99999 was not found"
}
405

메서드 허용되지 않음

요청 행에서 수신된 메서드는 원본 서버에 알려져 있지만 대상 리소스에서 지원되지 않습니다. 응답에는 유효한 메서드를 나열하는 Allow 헤더가 포함되어야 합니다.

일반적인 사용 사례: HTTP 메서드가 엔드포인트에서 지원되지 않을 때 반환됩니다. 예를 들어 읽기 전용 리소스에 DELETE 요청을 보내거나 GET만 지원하는 엔드포인트에 POST를 보내는 경우입니다.

RFC 9110
요청
DELETE /api/reports/monthly HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
응답
HTTP/1.1 405 Method Not Allowed
Content-Type: application/json
Allow: GET, HEAD

{
  "error": "method_not_allowed",
  "message": "DELETE is not allowed on this resource. Allowed methods: GET, HEAD"
}
406

수용 불가

요청에서 수신된 사전 콘텐츠 협상 헤더에 따르면 대상 리소스에 사용자 에이전트가 수용할 수 있는 표현이 없습니다.

일반적인 사용 사례: 서버가 클라이언트가 보낸 Accept 헤더와 일치하는 응답을 생성할 수 없을 때 반환됩니다. 예를 들어 클라이언트가 XML을 요청하지만 API가 JSON만 지원하는 경우입니다.

RFC 9110
407

프록시 인증 필요

401과 유사하지만 클라이언트가 프록시에서 인증해야 합니다. 프록시는 적용 가능한 인증 요구를 포함하는 Proxy-Authenticate 헤더를 반환해야 합니다.

일반적인 사용 사례: 클라이언트가 프록시 자체에 대한 유효한 자격 증명을 제공하지 않았을 때 프록시 서버에 의해 반환됩니다. 아웃바운드 트래픽이 인증된 프록시를 거치는 기업 네트워크 환경에서 흔합니다.

RFC 9110
408

요청 시간 초과

서버가 대기할 준비가 된 시간 내에 완전한 요청 메시지를 받지 못했습니다. 클라이언트는 나중에 수정 없이 요청을 반복할 수 있습니다.

일반적인 사용 사례: 클라이언트가 전체 요청을 보내는 데 너무 오래 걸릴 때 반환됩니다. 느린 연결, 신뢰할 수 없는 네트워크를 통한 대용량 업로드 또는 클라이언트가 연결을 열었지만 데이터를 보내지 않을 때 발생할 수 있습니다.

RFC 9110
409

충돌

대상 리소스의 현재 상태와의 충돌로 인해 요청을 완료할 수 없습니다. 클라이언트는 충돌을 해결하고 요청을 다시 제출할 수 있어야 합니다.

일반적인 사용 사례: 요청이 기존 데이터와 충돌할 때 사용됩니다. 예를 들어 이미 존재하는 이메일로 사용자를 생성하거나 마지막으로 가져온 이후 다른 요청에 의해 수정된 리소스를 업데이트하려는 경우입니다.

RFC 9110
요청
POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "Jane Doe",
  "email": "jane@example.com"
}
응답
HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": "conflict",
  "message": "A user with email jane@example.com already exists",
  "existing_id": 42
}
410

사라짐

대상 리소스가 원본 서버에서 더 이상 사용할 수 없으며 이 상태는 영구적일 가능성이 높습니다. 404와 달리 리소스가 한때 존재했지만 의도적으로 제거되었음을 명시적으로 나타냅니다.

일반적인 사용 사례: 리소스가 의도적이고 영구적으로 삭제되었을 때 사용됩니다. 일시적일 수 있는 404와 달리 검색 엔진에 URL을 인덱스에서 제거해야 함을 알립니다.

RFC 9110
411

길이 필요

서버가 정의된 Content-Length 헤더가 없는 요청을 거부합니다. 유효한 Content-Length 헤더가 추가되면 클라이언트는 요청을 반복할 수 있습니다.

일반적인 사용 사례: 서버가 요청에 Content-Length 헤더의 존재를 요구할 때 반환됩니다. 일반적으로 서버가 사전에 페이로드 크기를 알아야 하는 업로드 또는 POST 요청에서 발생합니다.

RFC 9110
412

전제 조건 실패

요청 헤더 필드에 주어진 하나 이상의 조건이 서버에서 테스트할 때 false로 평가되었습니다. If-Match 또는 If-Unmodified-Since와 같은 조건부 요청에 사용됩니다.

일반적인 사용 사례: 클라이언트가 마지막으로 가져온 이후 리소스가 수정되어 조건부 업데이트가 실패할 때 반환됩니다. API에서 낙관적 동시성 제어를 구현하는 데 사용됩니다.

RFC 9110
413

콘텐츠가 너무 큼

요청 페이로드가 서버가 처리할 수 있거나 처리하려는 것보다 크기 때문에 서버가 요청 처리를 거부합니다. 서버는 연결을 닫거나 Retry-After 헤더를 반환할 수 있습니다.

일반적인 사용 사례: 파일 업로드 또는 요청 본문이 서버의 설정된 최대 크기 제한을 초과할 때 반환됩니다. 예를 들어 10MB 제한이 있는 엔드포인트에 100MB 파일을 업로드하는 경우입니다.

RFC 9110
414

URI가 너무 김

요청 대상이 서버가 해석하려는 것보다 길기 때문에 서버가 요청 처리를 거부합니다. GET 요청의 쿼리 매개변수가 과도하게 긴 경우 발생할 수 있습니다.

일반적인 사용 사례: URL이 서버의 최대 길이를 초과할 때 반환됩니다. POST 요청 본문에 보내는 대신 쿼리 매개변수에 너무 많은 데이터를 인코딩할 때 자주 발생합니다.

RFC 9110
415

지원되지 않는 미디어 유형

페이로드가 대상 리소스의 이 메서드에서 지원되지 않는 형식이므로 원본 서버가 요청 처리를 거부합니다. Content-Type 또는 Content-Encoding이 허용되지 않습니다.

일반적인 사용 사례: 서버가 요청에서 보낸 Content-Type을 지원하지 않을 때 반환됩니다. 예를 들어 application/json만 허용하는 엔드포인트에 form-urlencoded 데이터를 보내는 경우입니다.

RFC 9110
416

범위를 충족할 수 없음

요청된 범위 중 선택된 표현에 대해 충족할 수 있는 범위가 없기 때문에 요청의 Range 헤더 필드의 범위 세트가 거부되었습니다.

일반적인 사용 사례: 클라이언트가 리소스 크기를 벗어나는 바이트 범위를 요청할 때 반환됩니다. 예를 들어 500바이트 파일의 1000-2000 바이트를 요청하는 경우입니다.

RFC 9110
417

기대 실패

요청의 Expect 헤더 필드에 주어진 기대를 하나 이상의 수신 서버가 충족할 수 없었습니다.

일반적인 사용 사례: 서버가 Expect 헤더에 지정된 요구 사항을 충족할 수 없을 때 반환됩니다. 가장 흔하게 Expect: 100-continue 메커니즘과 관련되며, 서버가 본문 전송 전에 요청을 거부하는 경우입니다.

RFC 9110
418

나는 찻주전자입니다

찻주전자로 커피를 끓이려는 시도는 이 오류 코드를 반환해야 합니다. 이것은 Hyper Text Coffee Pot Control Protocol에서 만우절 농담으로 정의되었지만 문화적 상징으로 보존되었습니다.

일반적인 사용 사례: 만우절 RFC의 이스터 에그 상태 코드입니다. API에서 유머러스한 응답으로 사용되거나 서버가 터무니없다고 판단하는 요청에 대한 의도적인 거부로 사용되기도 합니다.

RFC 2324
421

잘못 전달된 요청

요청이 응답을 생성할 수 없는 서버로 전달되었습니다. 서버가 요청 URI의 스킴과 권한 조합에 대한 응답을 생성하도록 구성되지 않은 경우 발생할 수 있습니다.

일반적인 사용 사례: HTTP/2에서 서버가 처리할 수 없는 다른 호스트 이름에 대해 연결이 재사용될 때 발생할 수 있습니다. 클라이언트는 다른 연결에서 요청을 재시도해야 합니다.

RFC 9110
422

처리할 수 없는 콘텐츠

서버가 콘텐츠 유형을 이해하고 요청 구문이 올바르지만 포함된 지시를 처리할 수 없었습니다. 요청은 잘 형성되어 있지만 의미적으로 유효하지 않습니다.

일반적인 사용 사례: 요청 본문이 구문적으로 유효한 JSON이지만 비즈니스 로직 검증에 실패할 때 사용됩니다. 예를 들어 음수 가격 설정, 과거 일정의 회의 예약 또는 시작일보다 이전인 종료일 제공 등입니다.

RFC 9110
요청
POST /api/events HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "title": "Team Meeting",
  "start_date": "2025-12-01",
  "end_date": "2025-11-01"
}
응답
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
  "error": "unprocessable_entity",
  "message": "Semantic validation failed",
  "details": [
    { "field": "end_date", "message": "End date must be after start date" }
  ]
}
423

잠김

메서드의 소스 또는 대상 리소스가 잠겨 있습니다. 클라이언트는 나중에 다시 시도하거나 잠금 해제를 요청해야 합니다.

일반적인 사용 사례: WebDAV에서 리소스가 다른 사용자나 프로세스에 의해 잠겨 있을 때 사용됩니다. API에서도 리소스가 다른 사용자에 의해 편집을 위해 일시적으로 잠겨 있음을 나타내는 데 사용할 수 있습니다.

RFC 4918
424

의존성 실패

요청된 작업이 실패한 다른 작업에 의존했기 때문에 리소스에 대해 메서드를 수행할 수 없었습니다.

일반적인 사용 사례: WebDAV에서 작업이 의존하는 전제 조건 작업도 실패하여 작업이 실패할 때 사용됩니다. 예를 들어 하위 파일 중 하나의 복사가 실패하여 디렉토리 복사가 실패하는 경우입니다.

RFC 4918
425

너무 이른

TLS 1.3 조기 데이터(0-RTT) 사용 시 잠재적인 재전송 공격을 피하기 위해 서버가 재전송될 수 있는 요청을 처리하는 것을 원하지 않습니다.

일반적인 사용 사례: 요청이 TLS 1.3 조기 데이터(0-RTT)에서 도착하고 서버가 이미 처리되지 않았음을 보장할 수 없을 때 사용됩니다. 비멱등 요청에 대한 재전송 공격을 방지합니다.

RFC 8470
426

업그레이드 필요

서버가 현재 프로토콜을 사용한 요청 수행을 거부하지만 클라이언트가 다른 프로토콜로 업그레이드한 후에는 수행할 의향이 있을 수 있습니다. 서버는 필요한 프로토콜을 나타내는 Upgrade 헤더를 포함해야 합니다.

일반적인 사용 사례: 서버가 클라이언트에게 새로운 프로토콜 버전으로의 전환을 요구할 때 사용됩니다. 예를 들어 HTTP/1.1에서 HTTP/2로의 업그레이드 또는 암호화되지 않은 연결에서 TLS로의 전환 등입니다.

RFC 9110
428

전제 조건 필요

원본 서버가 요청이 조건부일 것을 요구합니다. 이는 한 클라이언트가 GET으로 리소스를 가져와 수정한 후 PUT으로 돌려보내는 동안 다른 클라이언트도 수정한 '손실된 업데이트' 문제를 방지하기 위한 것입니다.

일반적인 사용 사례: 서버가 동시 수정 문제를 방지하기 위해 If-Match 또는 If-Unmodified-Since와 같은 조건부 헤더를 요구할 때 반환됩니다. 클라이언트에 낙관적 잠금 구현을 강제합니다.

RFC 6585
429

너무 많은 요청

사용자가 주어진 시간 내에 너무 많은 요청을 보냈습니다(속도 제한). 응답에는 새 요청을 보내기 전에 얼마나 기다려야 하는지를 나타내는 Retry-After 헤더가 포함되어야 합니다.

일반적인 사용 사례: 클라이언트가 API 속도 제한을 초과할 때 반환됩니다. 대부분의 API가 남용 방지와 공정한 사용을 보장하기 위해 이를 사용합니다. 클라이언트는 Retry-After 헤더에 지정된 시간 후에 백오프하고 재시도해야 합니다.

RFC 6585
요청
GET /api/search?q=test HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
응답
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1735689600

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Maximum 100 requests per minute.",
  "retry_after": 60
}
431

요청 헤더 필드가 너무 큼

서버가 헤더 필드가 너무 크기 때문에 요청을 처리하지 않으려 합니다. 요청 헤더 필드의 크기를 줄인 후 요청을 다시 제출할 수 있습니다.

일반적인 사용 사례: 요청 헤더가 서버의 크기 제한을 초과할 때 반환됩니다. 쿠키가 너무 커지거나 사용자 정의 헤더 또는 과도한 크기의 Authorization 토큰에 너무 많은 데이터가 전달될 때 흔히 발생합니다.

RFC 6585
451

법적 사유로 이용 불가

법적 요구의 결과로 서버가 리소스에 대한 접근을 거부하고 있습니다. 응답은 본문에 법적 제한에 대한 설명과 법적 권한을 식별하기 위한 Link 헤더를 포함해야 합니다.

일반적인 사용 사례: 정부 검열 명령, DMCA 삭제 통지, 법원 명령 또는 제재 준수 등의 법적 요구 사항으로 리소스가 차단될 때 사용됩니다. 코드 번호는 화씨 451을 참조합니다.

RFC 7725

5xx 서버 오류

11개의 상태 코드

500

내부 서버 오류

서버가 요청을 처리하지 못하게 하는 예상치 못한 상황을 만났습니다. 더 구체적인 5xx 상태 코드가 적절하지 않을 때의 일반적인 포괄 오류입니다.

일반적인 사용 사례: 가장 흔한 서버 오류입니다. 서버가 처리되지 않은 예외, 버그, 데이터베이스 연결 실패 또는 요청 처리 중 다른 예기치 않은 문제를 만났을 때 반환됩니다.

RFC 9110
응답
HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error": "internal_server_error",
  "message": "An unexpected error occurred. Please try again later.",
  "request_id": "req_abc123xyz"
}
501

구현되지 않음

서버가 요청을 처리하는 데 필요한 기능을 지원하지 않습니다. 서버가 요청 메서드를 인식하지 못하고 지원할 수 없을 때의 적절한 응답입니다.

일반적인 사용 사례: 서버가 요청된 HTTP 메서드를 인식하지 못하거나 아직 구현하지 않았을 때 반환됩니다. 계획되었지만 아직 구축되지 않은 API 엔드포인트의 자리 표시자로 사용할 수 있습니다.

RFC 9110
502

잘못된 게이트웨이

서버가 게이트웨이 또는 프록시로 작동하면서 요청을 처리하기 위해 접근한 업스트림 서버로부터 잘못된 응답을 받았습니다.

일반적인 사용 사례: 리버스 프록시, 로드 밸런서 또는 API 게이트웨이에서 업스트림 애플리케이션 서버가 잘못된 응답을 보내거나, 충돌하거나, 연결할 수 없을 때 반환됩니다. 배포 중에 흔합니다.

RFC 9110
응답
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

{
  "error": "bad_gateway",
  "message": "The upstream server returned an invalid response. Please try again shortly."
}
503

서비스 이용 불가

서버가 일시적인 과부하 또는 예정된 유지보수로 인해 현재 요청을 처리할 수 없습니다. 이는 일시적인 상태이며 서버가 곧 다시 사용할 수 있게 됨을 의미합니다.

일반적인 사용 사례: 계획된 유지보수 기간, 서버 과부하 또는 중요한 의존성이 다운되었을 때 반환됩니다. Retry-After 헤더로 클라이언트가 언제 다시 시도해야 하는지 나타낼 수 있습니다.

RFC 9110
응답
HTTP/1.1 503 Service Unavailable
Content-Type: application/json
Retry-After: 300

{
  "error": "service_unavailable",
  "message": "Service is temporarily unavailable for scheduled maintenance. Expected back at 2025-12-01T03:00:00Z.",
  "retry_after": 300
}
504

게이트웨이 시간 초과

서버가 게이트웨이 또는 프록시로 작동하면서 요청을 완료하기 위해 접근해야 했던 업스트림 서버로부터 시기적절한 응답을 받지 못했습니다.

일반적인 사용 사례: 리버스 프록시 또는 로드 밸런서에서 업스트림 애플리케이션 서버가 응답하는 데 너무 오래 걸릴 때 반환됩니다. 느린 데이터베이스 쿼리, 외부 API 시간 초과 또는 과부하된 백엔드를 나타내는 경우가 많습니다.

RFC 9110
505

HTTP 버전 미지원

서버가 요청 메시지에 사용된 HTTP의 주요 버전을 지원하지 않거나 지원을 거부합니다.

일반적인 사용 사례: 서버가 요청에 사용된 HTTP 프로토콜 버전을 지원하지 않을 때 반환됩니다. 예를 들어 HTTP/1.1만 지원하는 서버가 처리할 수 없는 HTTP/2 요청을 받은 경우입니다.

RFC 9110
506

변형도 협상함

서버에 내부 구성 오류가 있습니다: 선택된 변형 리소스가 자체적으로 투명한 콘텐츠 협상에 참여하도록 구성되어 순환 참조가 발생합니다.

일반적인 사용 사례: 서버 측 콘텐츠 협상의 잘못된 구성을 나타내는 드문 오류로, 협상된 리소스 자체가 협상을 시도하여 무한 루프를 생성합니다.

RFC 2295
507

저장 공간 부족

서버가 요청을 성공적으로 완료하는 데 필요한 표현을 저장할 수 없어 리소스에 대해 메서드를 수행할 수 없었습니다.

일반적인 사용 사례: 서버가 데이터를 쓰려는 동안 디스크 공간이나 저장 할당량이 부족할 때 반환되는 WebDAV 상태입니다. 저장 한도에 도달한 API에도 적용될 수 있습니다.

RFC 4918
508

루프 감지됨

서버가 'Depth: infinity' 요청을 처리하는 동안 무한 루프를 발견하여 작업을 종료했습니다. 이는 500의 더 구체적인 버전입니다.

일반적인 사용 사례: 서버가 리소스 바인딩에서 순환 종속성이나 무한 루프를 감지할 때 반환되는 WebDAV 상태입니다. 예를 들어 자기 자신을 참조하는 디렉토리 구조 등입니다.

RFC 5842
510

확장되지 않음

리소스에 접근하기 위한 정책이 요청에서 충족되지 않았습니다. 서버는 클라이언트가 확장 요청을 발행하는 데 필요한 모든 정보를 보내야 합니다.

일반적인 사용 사례: 서버가 요청을 충족하기 위해 요청에 대한 추가 확장이 필요함을 나타내는 거의 사용되지 않는 상태 코드입니다. HTTP Extension Framework 사양에 정의되어 있습니다.

RFC 2774
511

네트워크 인증 필요

클라이언트가 네트워크 접근을 얻기 위해 인증해야 합니다. 이는 HTTP 수준 인증이 아닌 캡티브 포털 로그인과 같은 네트워크 수준 접근에 관한 것입니다.

일반적인 사용 사례: 사용자가 아직 네트워크에 인증하지 않았을 때 캡티브 포털(예: 호텔 또는 공항 Wi-Fi 로그인 페이지)에서 반환됩니다. 응답 본문에는 일반적으로 로그인 페이지가 포함됩니다.

RFC 6585

관련 가이드

36개의 헤더

HTTP 헤더

주요 HTTP 헤더의 구문, 예제, 일반적인 값에 대한 설명.

탐색
9개의 메서드

HTTP 메서드

HTTP 요청 메서드의 완전한 가이드(비교표 및 예제 포함).

탐색
70개의 MIME 유형

MIME 유형

파일 확장자, 카테고리 및 사용 예제를 포함한 일반적인 MIME 유형의 완전한 레퍼런스.

탐색
10개의 헤더

CORS 설명

Cross-Origin Resource Sharing 완전 가이드 — 작동 방식, 모든 헤더 설명, 일반적인 오류와 해결 방법.

탐색

RequestDock에서 사용해 보기

실제 HTTP 요청을 보내고 응답을 검사하세요 — 브라우저에서 바로.

RequestDock 열기