HTTP 상태 코드: 무슨 뜻이고 언제 쓰는지

API가 200을 반환해. 응답 본문이 {"error": "Not found"}라고 해.

이건 틀렸어. 상태 코드는 이유가 있어 존재해. 제대로 써.

다섯 카테고리

1xx — 정보성. 실전에선 거의 안 보여.

2xx — 성공. 요청이 작동했어.

3xx — 리다이렉션. 다른 곳으로 가.

4xx — 클라이언트 에러. 네가 뭔가 잘못했어.

5xx — 서버 에러. 우리가 뭔가 잘못했어.

실제로 쓸 코드들

성공 (2xx)

200 OK — 표준 성공. 데이터를 반환하는 GET 요청에 써.

201 Created — 리소스가 생성됨. 뭔가 만드는 성공적인 POST 후에 써.

204 No Content — 성공, 하지만 반환할 게 없어. 데이터를 반환하지 않는 DELETE나 업데이트에 써.

클라이언트 에러 (4xx)

400 Bad Request — 잘못된 요청. 유효하지 않은 JSON, 필수 필드 누락, 잘못된 데이터 타입.

401 Unauthorized — 인증 없음. 사용자가 로그인해야 해.

403 Forbidden — 인증됐지만 허용 안 됨. 사용자는 존재하지만 권한이 부족해.

404 Not Found — 리소스가 존재하지 않아. 클래식.

409 Conflict — 요청이 현재 상태와 충돌. 중복 사용자 이름, 버전 불일치.

422 Unprocessable Entity — 문법적으로 맞지만 의미적으로 틀림. 유효한 JSON이지만 비즈니스 규칙 위반.

429 Too Many Requests — 속도 제한. 느려져.

서버 에러 (5xx)

500 Internal Server Error — 일반 서버 실패. 뭔가 충돌했어.

502 Bad Gateway — 업스트림 서버 실패. 네 서버는 괜찮은데 의존하는 뭔가가 아니야.

503 Service Unavailable — 일시적으로 다운. 유지보수나 과부하.

504 Gateway Timeout — 업스트림 서버가 제시간에 응답하지 않았어.

흔한 실수

본문에 에러가 있는 200. 에러면 에러 상태 코드 써. 성공했는지 알려고 클라이언트가 본문을 파싱하게 만들지 마.

검증 에러에 500. 사용자가 잘못된 데이터를 제출했어? 그건 400이나 422지 500이 아니야. 서버가 망가진 게 아니라—요청이야.

401 vs 403 혼란. 401은 "너 누구야?"를 의미해. 403은 "너 누군지 알지만 안 돼"야.

모든 것에 404. "Not found"가 항상 올바른 답은 아니야. 틀린 메서드? 405. 속도 제한? 429.

API 디자인하기

구체적으로 해. 클라이언트가 구체적 에러를 똑똑하게 처리할 수 있어. 일반 에러는 일반 처리를 의미해.

본문에 에러 세부사항 포함:

{
  "error": "validation_failed",
  "message": "Email format is invalid",
  "field": "email"
}

상태 코드는 문제의 카테고리를 말해. 본문이 구체적으로 설명해.

클라이언트로서 상태 코드 처리

2xx — 응답 파싱, 정상 진행.

4xx — 네 잘못. 로깅, 사용자에게 표시, 요청 수정.

5xx — 서버 잘못. 백오프로 재시도할 수도. 알림할 수도.

3xx — 자동으로 리다이렉트 따라가 (대부분의 HTTP 클라이언트가 해).

그냥 200만 확인하지 마. 성공 (2xx)을 확인하고 다른 경우를 적절히 처리해.

---

상태 코드는 의사소통이야. 올바르게 쓰면 API가 자기 문서화돼. 잘못 쓰면 디버깅이 추측이 돼.