API 에러 응답의 형식이 일정하지 않을 때 고치는 방법

API 에러 응답이 일정하지 않으면 클라이언트 개발이 어려워진다. 문제를 크게 잡으면 모든 파일이 의심스러워서 손 댈 곳을 못 찾는다.

핵심은 요청/응답 전체 흐름에서 원인을 찾고, 눈으로 확인할 수 있는 값부터 모으는 것이다.

현재 상황 파악

먼저 어떤 에러가 일정하지 않은지 정확히 정의한다. 같은 요청을 했을 때 응답 형식이 달라지는가?

curl -i 'https://example.com/api/items?page=1'

여러 번 요청해보고, 응답이 일정한지 확인한다.

첫 번째 단서: 인증 상태

API 요청이 제대로 인증되었나 확인한다. 토큰이 있나, 토큰이 유효한가.

인증 실패 시 에러 응답이 다를 수 있다.

두 번째 단서: 응답 코드와 body

HTTP 상태 코드는 뭔가. 400, 401, 500? 각 상태 코드마다 응답 형식을 정의해야 한다.

응답 body는 JSON인가, 텍스트인가. 에러 메시지는 뭐가 들어있나.

• 먼저 볼 것: HTTP 상태 코드와 응답 body
• 비교할 것: 정상일 때의 요청/응답 상태
• 기록할 것: 명령어, 상태 코드, 응답 형식

직접 확인하는 명령

curl로 여러 상황을 테스트해본다. 정상 요청, 잘못된 파라미터, 인증 실패, 서버 에러 등.

각각의 응답이 어떻게 다른지 기록한다.

인증 상태 재확인

API 인증이 제대로 작동하는지 다시 한 번 확인한다. 같은 조건에서 요청했을 때 응답이 일정한가.

검증

1. 같은 조건에서 요청했을 때 응답이 일정한가 확인한다.
2. 로그에서 뭐가 달라졌는지 설명한다.
3. 클라이언트에서 실제로 에러를 제대로 처리할 수 있는지 확인한다.

에러 응답 형식을 정리하면 클라이언트 개발이 훨씬 쉬워진다. 이번 확인을 기록해두면 다음 API 설계할 때도 도움이 된다.