클라이언트와 서버가 웹에서 소통할 때, 그들은 단순히 데이터를 주고받는 것을 넘어 서로의 요청과 응답이 어떤 상태인지를 알려주는 약속된 신호를 사용합니다. 이 신호가 바로 HTTP 상태 코드(HTTP Status Code)입니다. 200, 404, 500과 같은 이 숫자들은 단순한 에러 코드가 아니라, API의 예측 가능성과 안정성을 결정하고, 클라이언트 개발자가 디버깅을 효율적으로 수행할 수 있게 하는 매우 중요한 커뮤니케이션 도구입니다.
잘 설계된 API는 상황에 맞는 정확한 상태 코드를 반환함으로써, 클라이언트에게 명확한 피드백을 제공하고 불필요한 추측을 없애줍니다. 이 글에서는 개발자가 반드시 알아야 할 주요 HTTP 상태 코드를 체계적으로 분류하고, 실제 API 설계 시 어떤 코드를 선택해야 하는지에 대한 명확한 가이드를 제시합니다.
1xx: 정보 제공 (Informational)
1xx 계열 코드는 요청이 수신되어 처리 중임을 나타내며, 자주 사용되지는 않지만 특정 상황에서 중요한 역할을 합니다.
| 상태 코드 | 의미 | 설명 |
|---|---|---|
| 100 | Continue | 요청의 시작 부분만 받았으며, 클라이언트가 본문을 계속 보내도 좋다는 신호입니다. 대용량 데이터를 업로드할 때 사용될 수 있습니다. |
| 101 | Switching Protocols | 클라이언트의 Upgrade 헤더 요청에 따라 서버가 프로토콜을 전환했음을 알립니다. 대표적으로 HTTP에서 WebSocket으로 전환될 때 사용됩니다. |
2xx: 성공 (Success)
2xx 계열 코드는 클라이언트의 요청이 성공적으로 수신, 이해, 그리고 처리되었음을 의미합니다. API 개발 시 가장 기분 좋게 마주하는 코드들입니다.
| 상태 코드 | 의미 | 설명 |
|---|---|---|
| 200 | OK | 요청이 성공했음을 나타내는 가장 일반적인 응답입니다. GET, PUT, PATCH 요청에 대한 성공 응답으로 주로 사용됩니다. |
| 201 | Created | 요청이 성공하여 새로운 리소스가 생성되었음을 의미합니다. 주로 POST 요청이나 일부 PUT 요청에 대한 응답으로 사용되며, 보통 Location 헤더에 생성된 리소스의 URI를 포함하여 반환합니다. |
| 204 | No Content | 요청은 성공했지만, 클라이언트에게 보낼 응답 본문(body)이 없음을 의미합니다. DELETE 요청으로 리소스를 성공적으로 삭제했거나, PUT 요청으로 리소스를 수정했지만 클라이언트에 별도 데이터를 보낼 필요가 없을 때 유용합니다. |
| 206 | Partial Content | 클라이언트가 Range 헤더를 사용해 리소스의 일부만 요청했을 때, 해당 부분만 성공적으로 전송했음을 나타냅니다. 대용량 파일 다운로드나 영상 스트리밍에서 사용됩니다. |
3xx: 리디렉션 (Redirection)
3xx 계열 코드는 요청을 완료하기 위해 클라이언트가 추가적인 조치를 취해야 함을 알립니다. 주로 리소스의 위치가 변경되었을 때 사용됩니다.
| 상태 코드 | 의미 | 설명 |
|---|---|---|
| 301 | Moved Permanently | 요청한 리소스의 URI가 영구적으로 변경되었음을 알립니다. 검색 엔진은 이 응답을 받으면 해당 리소스의 주소를 업데이트합니다. (SEO에 중요) |
| 302 | Found | 요청한 리소스가 일시적으로 다른 URI에 있음을 의미합니다. 클라이언트는 향후 요청에서도 원래 URI를 계속 사용해야 합니다. 로그인 후 원래 페이지로 이동시키는 등의 임시 리디렉션에 사용됩니다. |
| 304 | Not Modified | 클라이언트가 조건부 요청(e.g., If-None-Match, If-Modified-Since 헤더)을 보냈을 때, 리소스가 변경되지 않았음을 알립니다. 이 경우 클라이언트는 캐시된 버전을 사용하며, 불필요한 데이터 전송을 막아 성능을 향상시킵니다. |
4xx: 클라이언트 오류 (Client Error)
4xx 계열 코드는 클라이언트 측에 오류의 원인이 있음을 나타냅니다. API를 사용하는 개발자에게 가장 중요한 피드백이 되므로, 명확하고 정확하게 사용해야 합니다.
| 상태 코드 | 의미 | 설명 |
|---|---|---|
| 400 | Bad Request | 요청 문법이 잘못되었거나, 파라미터 값이 유효하지 않는 등 클라이언트의 요청 자체가 잘못되었음을 의미하는 범용적인 코드입니다. (e.g., 필드 누락, JSON 파싱 오류) |
| 401 | Unauthorized | 인증(Authentication)이 필요함을 의미합니다. 클라이언트는 유효한 인증 정보를 제공하지 않았습니다. 로그인하지 않은 사용자가 보호된 리소스에 접근하려 할 때 사용됩니다. |
| 403 | Forbidden | 클라이언트가 리소스에 대한 접근 권한(Authorization)이 없음을 의미합니다. 서버는 클라이언트가 누구인지 알고 있지만(인증됨), 작업을 수행할 권한을 허용하지 않습니다. (e.g., 일반 사용자가 관리자 페이지 접근 시) |
| 404 | Not Found | 요청한 리소스를 서버에서 찾을 수 없음을 의미합니다. API 엔드포인트가 존재하지 않거나, 특정 ID의 데이터가 없을 때 사용됩니다. |
| 405 | Method Not Allowed | 요청한 리소스에 대해 허용되지 않은 HTTP 메서드를 사용했음을 의미합니다. 예를 들어, 읽기 전용 리소스에 POST 요청을 보낼 때 사용되며, Allow 헤더에 허용되는 메서드 목록을 포함하여 응답해야 합니다. |
| 413 | Payload Too Large | 요청 본문의 크기가 서버가 처리할 수 있는 한도를 초과했을 때 사용됩니다. (e.g., 파일 업로드 크기 제한 초과) |
| 415 | Unsupported Media Type | 서버가 요청 본문의 미디어 타입(e.g., Content-Type 헤더)을 지원하지 않음을 의미합니다. (e.g., JSON만 지원하는 API에 XML 데이터를 보낼 때) |
| 429 | Too Many Requests | 클라이언트가 지정된 시간 동안 너무 많은 요청을 보냈을 때(Rate Limiting) 사용됩니다. API 남용을 방지하기 위한 중요한 코드입니다. |
5xx: 서버 오류 (Server Error)
5xx 계열 코드는 명백히 서버 측에 문제의 원인이 있음을 나타냅니다.
| 상태 코드 | 의미 | 설명 |
|---|---|---|
| 500 | Internal Server Error | 서버에서 예상치 못한 오류가 발생하여 요청을 처리할 수 없음을 의미하는 가장 일반적인 서버 오류 코드입니다. 코드 내에서 처리되지 않은 예외가 발생했을 때 주로 나타납니다. |
| 502 | Bad Gateway | 게이트웨이나 프록시 역할을 하는 서버가 업스트림(백엔드) 서버로부터 잘못된 응답을 받았을 때 발생합니다. |
| 503 | Service Unavailable | 서버가 일시적으로 요청을 처리할 수 없음을 의미합니다. 서버가 과부하 상태이거나 유지보수를 위해 다운되었을 때 사용되며, Retry-After 헤더를 통해 언제 서비스가 재개될지 알려줄 수 있습니다. |
| 504 | Gateway Timeout | 게이트웨이나 프록시 서버가 업스트림 서버로부터 제시간에 응답을 받지 못했을 때 발생합니다. 백엔드 서버의 성능 문제나 네트워크 문제일 수 있습니다. |
RESTful API 설계 기준 상태 코드 매핑 요약
RESTful API를 설계할 때 각 HTTP 메서드에 대해 어떤 상태 코드를 반환할지 미리 정의해두면 일관성 있고 예측 가능한 API를 만들 수 있습니다.
| 동작 (HTTP 메서드) | 성공 시 | 실패 시 (클라이언트 원인) | 실패 시 (서버 원인) |
|---|---|---|---|
| GET | 200 OK | 404 Not Found, 401 Unauthorized, 403 Forbidden | 500 … |
| POST | 201 Created | 400 Bad Request, 401 Unauthorized, 403 Forbidden | 500 … |
| PUT / PATCH | 200 OK 또는 204 No Content | 400 Bad Request, 404 Not Found, 401 Unauthorized | 500 … |
| DELETE | 204 No Content | 404 Not Found, 401 Unauthorized, 403 Forbidden | 500 … |
HTTP 상태 코드는 단순한 숫자를 넘어 서버와 클라이언트 간의 명확한 약속입니다. 상황에 맞는 적절한 상태 코드를 사용하는 것은 API의 품질을 높이고, 이를 사용하는 개발자들의 개발 경험을 향상시키는 기본적이면서도 가장 중요한 실천입니다.
