14강. 오류 응답과 상태 코드 테스트

?1. 이번 강의에서 해결할 문제

게임 기록·랭킹 API를 테스트하면서 의도적인 실패 요청으로 오류 상태와 JSON 형식을 검증하는 문제를 해결합니다. 수동으로 한 번 성공하는 데서 끝내지 않고 같은 결과를 다시 확인할 수 있는 요청으로 남깁니다.

✓2. 학습 목표

✓이 강의를 마치면

• 이번 주제의 HTTP 계약을 설명할 수 있습니다.
• Postman에서 성공과 실패 요청을 각각 구성할 수 있습니다.
• PowerShell에서 핵심 요청을 재현하고 결과를 판정할 수 있습니다.

◇3. 핵심 개념

좋은 API는 성공뿐 아니라 오류도 일관된 계약을 가집니다. 400은 일반적인 잘못된 요청, 401은 인증 필요·실패, 403은 인증됐지만 권한 부족, 404는 리소스 없음, 409는 상태 충돌, 422는 입력 검증 실패에 주로 사용됩니다. 실제 API 계약이 우선이며 메시지 전문보다 안정적인 코드와 구조를 검증합니다.

실패 상황을 상태 코드에 연결하기

상황	기대 상태	클라이언트의 다음 행동
score 필드 누락·타입 오류	422	해당 입력 필드 안내
인증 토큰 없음·유효하지 않음	401	로그인 또는 토큰 갱신
로그인했지만 관리자 기능 접근	403	권한 부족 안내, 재로그인 반복 금지
존재하지 않는 player_id	404	목록으로 돌아가거나 대상 갱신
이미 존재하는 nickname 생성	409	다른 닉네임 입력 안내
처리 중 예상하지 못한 서버 오류	500	일반 오류 안내와 서버 로그 조사

오류 JSON의 가장 작은 계약

{
  "error": {
    "code": "PLAYER_NOT_FOUND",
    "message": "플레이어를 찾을 수 없습니다."
  }
}

테스트는 번역이나 문구 수정에 자주 바뀌는 message 전문보다 status, error.code, 필수 필드 구조를 우선 검증합니다. 사용자에게는 안전한 메시지를 주고, 스택·SQL·서버 파일 경로 같은 내부 진단 정보는 서버 로그에만 남깁니다.

✎4. 단계별 실습

실습 경로: C:\dev\game-ranking-api-tests

실행 전 상태: 성공 요청이 먼저 통과해야 합니다. 테스트용 로컬 DB와 계정을 사용하고, 실패 요청이 실제 운영 데이터나 계정을 변경하지 않는지 확인합니다.

1. 90 Error Cases에 누락 필드 422, 없는 ID 404, 중복 닉네임 409 요청을 저장합니다.
2. 각 요청 이름에 기대 상태를 적습니다.
3. 응답에 detail 또는 프로젝트 표준 error.code, error.message가 있는지 확인합니다.
4. 내부 스택·SQL·파일 경로가 노출되지 않는지 검사합니다.

구체적인 실패 결과 예

GET /players/999999
예상: 404
본문: detail 또는 PLAYER_NOT_FOUND 구조
금지: SQL SELECT 문, C:\... 서버 경로, Python stack trace

POST /records with {"game_name":"Rule Break"}
예상: 422 (필수 score 누락)
본문: 어느 필드 검증이 실패했는지 식별 가능
금지: 요청을 일부 저장하거나 500으로 처리

상태 코드만 맞아도 본문이 HTML 오류 페이지이거나 내부 정보가 노출되면 계약 통과가 아닙니다. 반대로 메시지 문장만 달라졌지만 안정적인 오류 코드와 구조가 같다면 테스트를 불필요하게 깨지 않도록 설계합니다.

PowerShell

try {
  Invoke-RestMethod -Uri "http://127.0.0.1:8000/players/999999"
} catch {
  Write-Host "status:" $_.Exception.Response.StatusCode.value__
  Write-Host "message:" $_.ErrorDetails.Message
}

PowerShell 결과 읽기

1. 존재하지 않을 가능성이 매우 높은 테스트 ID를 요청합니다.
2. PowerShell은 4xx를 catch로 보내므로 StatusCode와 ErrorDetails.Message를 각각 읽습니다.
3. status가 기대한 404인지, body가 JSON인지, 내부 정보가 없는지 별도로 판정합니다.
4. API가 실제로 200을 반환한다면 테스트 데이터에 그 ID가 생겼는지 먼저 확인하고 임의로 기대값을 바꾸지 않습니다.

Postman의 버튼·탭 이름은 버전에 따라 달라질 수 있습니다. 메뉴가 다르면 설치된 앱의 도움말과 Postman 공식 문서를 먼저 확인합니다.

→5. 요청과 응답이 동작하는 이유

FastAPI는 라우팅과 Pydantic 검증 단계에서 표준 오류를 만들 수 있고, 애플리케이션 예외 처리기가 도메인 오류를 통일합니다. 클라이언트는 상태 코드로 큰 범주를, JSON 오류 코드로 세부 원인을 구분합니다.

!6. 자주 하는 실수와 해결법

!자주 하는 실수

• 실수: 오류 메시지 한국어 문장 전체만 비교함 해결: 변경에 안정적인 상태와 오류 코드·필드 구조를 우선합니다.
• 실수: 500에 내부 정보가 보여도 방치함 해결: 스택·쿼리·비밀 값 노출은 보안 결함으로 기록합니다.
• 실수: 401과 403을 혼동함 해결: 신원 확인 실패와 권한 부족을 분리합니다.

✎7. 직접 실습

✎직접 실습

실습 목표

422·404·409 실패를 의도적으로 재현하고 상태·오류 구조·민감 정보 비노출을 회귀 요청으로 저장합니다.

시작 전 상태

먼저 해당 리소스의 성공 요청을 실행합니다. 실패 테스트용 값과 기존 데이터 상태를 기록하고 실제 토큰은 환경 변수에서만 참조합니다.

1단계: 따라 하기

없는 플레이어 ID를 요청해 404를 만들고 status, Content-Type, 오류 코드/필드를 기록합니다. PowerShell에서도 같은 요청을 재현합니다.

2단계: 입력을 바꾸고 비교하기

필수 score를 뺀 기록 생성으로 422를 만듭니다. 잘못된 타입과 누락 필드의 응답 경로가 어떻게 다른지 비교합니다.

3단계: 직접 적용

같은 닉네임을 두 번 생성해 409를 재현합니다. 테스트 후 생성된 학습 데이터를 정리하고, 각 요청 이름에 기대 상태를 포함합니다.

4단계: 스스로 확인

• 세 오류가 서로 다른 원인을 정확히 표현하나요?
• 메시지 전문이 아니라 안정적인 status·code·구조를 판정하나요?
• 응답에 스택·SQL·파일 경로·비밀 값이 없나요?

막혔을 때

• 기대 오류 대신 200: 테스트 데이터가 이미 예상과 다른지, method/path/body가 실제 실패 조건인지 확인합니다.
• 모든 실패가 500: 서버 로그에서 처리되지 않은 예외를 찾고 클라이언트 응답에는 내부 정보를 노출하지 않습니다.
• 401과 403이 뒤바뀜: 신원 확인이 됐는지부터 분리해 테스트합니다.
• 테스트가 문구 변경마다 깨짐: 메시지 전문 대신 오류 코드와 필수 JSON 경로를 검증합니다.

완료 후 Postman 요청을 저장하고, 실제 API Key·JWT·비밀번호가 이름·본문·스크립트·export 파일에 없는지 확인합니다.

?8. 이해 점검 질문 3개

?이해 점검

1. 401과 403의 의미 차이는 무엇인가요?
2. 오류 안내 문구가 번역으로 바뀌어도 자동 테스트를 안정적으로 유지하려면 어떤 필드를 우선 검증해야 하나요?
3. 500 응답에서 노출되면 안 되는 정보는 무엇인가요?

■9. 핵심 요약

■핵심 요약

실패 응답도 API 계약입니다. 대표 오류를 의도적으로 재현하고 상태, 안정적인 오류 구조, 민감 정보 비노출을 검증합니다.

§다음 강의 연결

실패 계약을 구분했으므로 15강. Bearer JWT에서 인증 없음 401과 인증됐지만 권한 부족 403을 실제 헤더 조건으로 검증합니다.