blevels

Home / AI / AI 용어사전 / HTTP 상태 코드 — 200·404·500이 보내는 신호 해독법

TERM

HTTP 상태 코드 — 200·404·500이 보내는 신호 해독법

게시일 2026-04-30수정일 2026-04-30
공식 링크
On this page

AI API를 호출했더니 응답으로 숫자 하나가 돌아온다. 200이면 안도하고, 404면 당혹하고, 500이면 막막해진다. 이 세 자리 숫자가 HTTP 통신의 상태를 압축해서 전달하는 언어다.

정의

HTTP 상태 코드(HTTP Status Code)는 클라이언트의 요청에 대해 서버가 응답할 때 함께 보내는 3자리 숫자 코드다. 요청이 성공했는지, 왜 실패했는지를 표준화된 방식으로 전달한다.

RFC 9110 표준에 정의되어 있으며, 첫 번째 자리(1~5)로 응답의 큰 분류를 구분한다.

5가지 클래스 분류

| 클래스 | 의미 | 예시 | |---|---|---| | 1xx | 정보 (처리 중) | 100 Continue | | 2xx | 성공 | 200 OK, 201 Created | | 3xx | 리다이렉션 | 301 Moved, 302 Found | | 4xx | 클라이언트 오류 | 400 Bad Request, 404 Not Found | | 5xx | 서버 오류 | 500 Internal Server Error |

자주 마주치는 핵심 코드

2xx — 성공

  • 200 OK: 요청 성공. GET/POST 응답의 기본값
  • 201 Created: 새 리소스 생성 성공 (POST로 데이터 등록 시)
  • 204 No Content: 성공했지만 응답 본문 없음 (DELETE 후 자주 사용)

4xx — 클라이언트 오류

  • 400 Bad Request: 요청 형식이 잘못됨. API 파라미터 누락·타입 오류
  • 401 Unauthorized: 인증 필요. jwt 토큰 없거나 만료됨
  • 403 Forbidden: 인증은 됐지만 권한 없음
  • 404 Not Found: 요청한 리소스가 존재하지 않음
  • 422 Unprocessable Entity: 형식은 맞지만 유효성 검사 실패
  • 429 Too Many Requests: 속도 제한(Rate Limit) 초과 — AI API에서 자주 발생

5xx — 서버 오류

  • 500 Internal Server Error: 서버 내부 오류. 원인을 서버 로그에서 확인해야 함
  • 502 Bad Gateway: 프록시/게이트웨이가 upstream에서 잘못된 응답 수신
  • 503 Service Unavailable: 서버 과부하 또는 유지보수 중
  • 504 Gateway Timeout: upstream 서버가 제시간에 응답하지 않음
AD

AI API 호출에서의 상태 코드

llm API(OpenAI, Anthropic 등)를 사용할 때 자주 만나는 상태 코드와 대응:

import anthropic

client = anthropic.Anthropic()

try:
    response = client.messages.create(...)
except anthropic.AuthenticationError:  # 401
    print("API 키를 확인하세요")
except anthropic.RateLimitError:  # 429
    print("요청 속도를 줄이세요 (지수 백오프 적용)")
except anthropic.APIStatusError as e:
    print(f"상태 코드: {e.status_code}")  # 500, 503 등

429 Too Many Requests는 AI API 사용 중 가장 자주 만나는 오류다. 지수 백오프(Exponential Backoff) — 1초, 2초, 4초, 8초 간격으로 재시도하는 패턴으로 대응한다.

활용 사례

  • API 디버깅: 응답 코드로 오류 위치(클라이언트/서버)를 빠르게 판별
  • 프론트엔드 오류 처리: 401이면 로그인 페이지로 리다이렉트, 404면 커스텀 오류 페이지 표시
  • 모니터링: 5xx 비율을 메트릭으로 수집해 서비스 안정성 지표로 활용

관련 용어

  • http-method — GET/POST/DELETE 등 요청 방식. 상태 코드와 함께 응답을 해석
  • api — 상태 코드를 응답으로 반환하는 인터페이스
  • jwt — 401 오류와 연결된 인증 토큰
  • rest — HTTP 상태 코드를 표준으로 활용하는 API 설계 방식
AD