Feature #1569
closedFeature #1529: [T06] 전체 API·DTO 계약 확정
[T06] 공통 에러 계약·에러 DTO·글로벌 예외 핸들러 (후속)
100%
Description
제목: [T06] 공통 에러 계약·에러 DTO·글로벌 예외 핸들러 (후속)
목표 및 사용자 시나리오: Backend가 모든 오류를 같은 형식으로 보내도록 공통 에러 계약을 확정하고, 에러 응답 DTO와 글로벌 예외 핸들러를 backend/에 구현 (PM 요청: 기능 API 구현 전 선행)
범위/비범위: 에러 DTO(ProblemDetail), 에러 코드 목록, 앱 예외 클래스, 글로벌 예외 핸들러(앱 예외·요청 검증 422·404/405·미처리 500), request_id, 테스트, 문서. 기능 API(T15~T18) 구현은 비범위
담당자: 이상재 (GitHub: sangjae-lee97)
선행조건: T06 (#1529, PR #29 머지 — API_CONTRACT.md §1.4 오류 규칙), T13 (#1498 Backend 골격)
관련 화면/API/DB: docs/API_CONTRACT.md §1.4, docs/api/openapi.yaml components.schemas.Problem, backend/app
완료조건(테스트·증빙 포함): 모든 오류가 application/problem+json + code + request_id로 응답, 422 필드 오류 목록, 미처리 예외는 내부 정보 없이 500, pytest PASS, CI PASS
예상 일정: 2026-11-06 ~
브랜치 / PR / Merge SHA: task/t06-error-contract / https://github.com/ai-career-platform/ai-career-platform/pull/41 / -
Staging 검증 결과: 해당 없음
링크
- API 계약 §1.4: https://github.com/ai-career-platform/ai-career-platform/blob/main/docs/API_CONTRACT.md
- Backend 골격: https://github.com/ai-career-platform/ai-career-platform/blob/main/backend/README.md
- 후행 일감: T15, T16, T17, T18, T21~T24
Subtasks
Related issues
상이 Updated by 상재 이 11 days ago
- Related to Feature #1529: [T06] 전체 API·DTO 계약 확정 added
상이 Updated by 상재 이 11 days ago
- Parent task set to #1529
T06(#1529) 하위 일감으로 등록 — https://sulfite-footbath-next.ngrok-free.dev/issues/1529
상이 Updated by 상재 이 11 days ago
- Description updated (diff)
- % Done changed from 10 to 90
PR 생성 + 리뷰 요청(Crasnec), CI Smoke Test PASS
https://github.com/ai-career-platform/ai-career-platform/pull/41
- 에러 형식: application/problem+json — type, title, status, code, request_id (+ 선택 detail, 422만 errors[{field, code}])
- 산출물: backend/app/schemas/error.py(DTO), app/core/errors.py(코드·예외), app/core/exception_handlers.py(글로벌 핸들러), app/core/request_id.py(X-Request-ID), tests/test_errors.py(31 passed)
- 문서: docs/API_CONTRACT.md §1.4, backend/README.md "공통 에러 처리"
- 검증: backend pytest 31 passed, docs/api/check_openapi.py PASS (operations=74, schemas=85, examples=173)
- Staging 변경 없음
상이 Updated by 상재 이 11 days ago
- Status changed from In Progress to Closed
- % Done changed from 90 to 100
완료 — PR #41 main 머지. 진척도 100%, 상태 Closed.
- PR: https://github.com/ai-career-platform/ai-career-platform/pull/41
- Merge SHA: 1aa17298d6d5fb1e9e25c8b47caee466b4a043db (2026-11-06, main)
h3. 머지된 최종 내용
- PM 피드백 반영: 공통 오류 응답을 application/json의 {code, status, message}로 확정. 요청 추적 ID는 X-Request-ID 헤더로 전달.
- ERROR_CATALOG에서 에러 코드별 HTTP 상태·사용자 메시지를 관리. 글로벌 예외 핸들러에서 앱 예외·요청 검증·404/405·미처리 500을 공통 형식으로 처리.
- API 계약서 §1.4와 OpenAPI 스키마·예시, 백엔드 사용 가이드 갱신.
h3. 검증
- 최종 구현 커밋 27d98e0 기준 pytest 52개 통과. 카탈로그·계약서·OpenAPI 예시 일치 검증 포함.
- Staging 변경 없음.