사용자가 저장 버튼을 눌렀는데 화면에는 ‘에러가 발생했습니다’만 뜹니다. 개발자 로그에는 다른 코드가 있고 고객 지원팀은 어느 요청인지 모릅니다. 클라이언트가 실패 유형을 알 수 없다면 무조건 재시도하거나, 사용자에게 다시 입력하라고 하거나, 아예 침묵하게 됩니다. API 오류 응답은 개발자만 읽는 로그가 아니라 제품의 복구 경로를 정하는 계약입니다.
HTTP 상태 코드부터 정직하게 쓴다
처리하지 못한 요청에 성공 상태를 보내고 본문에만 실패 코드를 넣으면 브라우저, 프록시, 모니터링 도구가 잘못 이해합니다. 인증 문제, 권한 부족, 찾을 수 없는 자원, 입력 검증 실패, 일시적 서버 문제는 다른 성격입니다. 적절한 HTTP 상태 코드는 범용 도구가 실패를 구분할 첫 신호입니다. 다만 상태 코드 하나로 ‘어느 필드가 문제인지’ 또는 ‘사용자가 무엇을 할지’까지 표현할 수는 없습니다.
RFC 9457 Problem Details는 공통적인 오류 표현을 제공합니다. application/problem+json 본문에 오류 유형을 식별하는 type, 짧은 제목 title, HTTP status, 구체적인 설명 detail, 개별 발생을 가리키는 instance 등을 사용할 수 있습니다. 모든 필드를 무조건 채우라는 뜻이 아니라, 클라이언트와 운영자가 일관되게 이해할 수 있는 형식을 정하라는 뜻입니다.
사람을 위한 설명과 기계를 위한 유형을 분리한다
‘이 주문은 이미 취소돼 승인할 수 없습니다’는 사람이 읽기 좋은 설명입니다. 클라이언트가 코드를 분기하려면 안정적인 오류 유형이 필요합니다. 번역되거나 문구가 다듬어질 수 있는 detail 문자열을 파싱하지 말고, 약속한 type이나 확장 오류 코드를 사용합니다. 오류 유형이 바뀌면 앱·웹 클라이언트도 함께 영향을 받으므로 버전과 호환성을 검토합니다.
입력 검증 오류는 어느 필드가 잘못됐는지 구조화해 보내면 폼에서 해당 필드를 강조할 수 있습니다. RFC 9457은 검증 오류의 위치와 설명을 담는 확장 예시를 제시합니다. 반면 내부 SQL 문장, 파일 경로, 토큰, 다른 고객 정보는 오류 본문에 넣지 않습니다. 개발자의 조사에 필요한 상세 내용은 접근이 통제된 서버 로그에 두고, 클라이언트에는 연결 가능한 추적 ID를 제공합니다.
재시도 가능한 실패를 명확히 구분한다
사용자가 형식을 잘못 입력했다면 같은 요청을 반복해도 해결되지 않습니다. 일시적인 과부하나 외부 서비스 장애라면 잠시 뒤 재시도가 적절할 수 있습니다. 하지만 재시도 가능한 응답이라도 쓰기 요청에서 중복 처리 위험이 있는지 따져야 합니다. 결제·주문 생성 같은 API에는 멱등성 키나 중복 방지 정책을 함께 설계합니다. 필요한 경우 Retry-After 같은 응답 헤더로 재시도 시점을 알릴 수 있지만, 클라이언트가 이를 지킬지와 최대 시도 횟수도 정해야 합니다.
화면과 지원 흐름까지 이어야 계약이 된다
오류 유형마다 사용자 행동을 적어 봅니다. 입력 수정이 필요한가, 권한 요청이 필요한가, 잠시 기다릴까, 지원팀에 문의할까? 화면 문구는 기술 용어를 그대로 노출하지 않아도 됩니다. 다만 고객 지원팀이 사용자의 화면 메시지와 서버의 추적 ID를 연결할 수 있어야 합니다. 오류 발생 시각, 요청 경로, 테넌트 식별자 같은 운영 정보는 개인정보 노출 범위를 고려해 로그에 안전하게 남깁니다.
계약 테스트에는 정상 성공뿐 아니라 대표 실패도 포함합니다. 각 오류의 상태 코드, 미디어 타입, 필수 필드, 타입 값, 민감정보 비노출을 검증합니다. 예외 처리가 빠진 엔드포인트가 HTML 오류 페이지를 반환하지 않는지도 확인합니다. 오류 응답까지 테스트해야 클라이언트가 예상한 복구 동작을 안정적으로 구현할 수 있습니다.
설계 체크리스트
- HTTP 상태와 본문 오류 유형이 서로 맞는가?
- 사용자에게 필요한 다음 행동을 구분할 수 있는가?
- 클라이언트가 번역 문구 대신 안정적인 유형으로 분기하는가?
- 내부 정보는 숨기고 지원용 추적 단서는 남기는가?
- 대표 오류가 계약 테스트에 포함돼 있는가?
오류가 없도록 만드는 것만큼 오류 뒤에 무엇이 일어나는지 정하는 일이 중요합니다. 좋은 오류 계약은 실패를 설명 가능한 상태로 바꾸고, 사용자가 다음 단계를 알게 합니다.
#API오류 #RFC9457 #ProblemDetails #HTTP상태코드 #오류응답 #API설계 #에러메시지 #오류코드 #API계약 #사용자경험
