API 응답이 예상과 다를 때 확인 순서

API를 다루다 보면 같은 요청을 보냈는데 다른 응답이 돌아오는 상황을 마주한다. 이런 때는 정답을 맞히려고 하기보다는, 체계적으로 요청과 응답의 각 부분을 확인해야 한다.

요청 파라미터부터 확인하기

API 문제를 진단할 때 가장 먼저 확인할 것은 내가 보낸 요청이 정말 맞는지이다. 쿼리 파라미터, 헤더, 바디 등을 모두 확인해야 한다.

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

이 명령은 요청의 모든 헤더와 응답 상태 코드를 함께 보여준다. 응답의 status code가 200인지 400인지 500인지에 따라 대응 방법이 완전히 달라진다.

인증 상태 확인하기

같은 엔드포인트인데 때로는 성공하고 때로는 실패한다면, 인증 상태를 의심해봐야 한다. API 토큰이 만료되지 않았는지, 권한이 제대로 부여되어 있는지 확인한다.

• 토큰을 요청 헤더에 제대로 담았는가
• 토큰이 아직 유효한 상태인가
• 사용자의 권한이 이 API에 접근할 수 있는 수준인가

로컬과 서버 환경의 차이 파악하기

ローカル環境では動くのに本番環境では動かないという状況は、環境による差異が原因です。데이터베이스의 상태, 캐시 상태, 시간대 설정 등이 다를 수 있다. 같은 요청을 로컬과 서버 양쪽에서 해보고, 응답을 비교하는 게 좋다.

응답 바디를 꼼꼼히 읽기

같은 상태 코드 200을 받았더라도 응답 본문이 다를 수 있다. 예를 들어 예상한 필드가 없거나, 다른 필드가 추가돼 있을 수 있다. JSON 응답을 받았다면 직접 눈으로 읽어보면서 서버가 정말 요청한 데이터를 주는지 확인한다.

진단 흐름 정하기

같은 문제를 반복적으로 해결하지 않으려면 진단 순서를 미리 정해두는 게 좋다:

1. 현재 상황에서 증상을 다시 확인한다.
2. 요청의 각 부분(파라미터, 헤더, 바디)을 로그에 남긴다.
3. 응답의 상태 코드와 본문을 기록한다.
4. 한 가지만 바꿔서 테스트한다.

작은 확인들이 모이면 자연스럽게 원인이 드러난다.