API 응답이 이상할 때 처음 확인할 것들

API 디버깅할 때 내가 자주 하는 실수는 응답 데이터 구조부터 고쳐보려는 것이다. 근데 대부분의 경우 요청 단계에서 뭔가 틀려있었다.

먼저 status code 확인

API가 정상인지 아닌지는 status code로 대부분 판단할 수 있다. 응답 body를 보기 전에 항상 status code부터 확인한다.

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

200이 나오면 기본 흐름은 맞다는 뜻이다. 401이나 403이 나오면 인증/권한 문제, 400이면 요청 데이터가 빠졌거나 형식이 틀렸다는 뜻이다.

응답 body와 정상 상태 비교

정상 응답이 뭔지 먼저 정해두면 디버깅 속도가 훨씬 빨라진다. 같은 엔드포인트에서 파라미터만 다르게 줬을 때 응답이 어떻게 바뀌는지 기록해두면, 나중에 문제가 생겼을 때 원인을 좁히기 쉬워진다.

# 정상: 페이지 1
curl -s 'https://example.com/api/items?page=1' | jq '.items | length'

# 비교: 페이지 2
curl -s 'https://example.com/api/items?page=2' | jq '.items | length'

로컬과 배포 환경 확인

로컬에서는 잘 작동하는데 배포되면 안 되는 경우가 많다. 이럴 땐 환경변수부터 확인한다. API 키, 데이터베이스 연결 URL, 타임존 설정 같은 것들이 다를 수 있다.

로그에 기록할 때 요청 파라미터와 응답 코드를 함께 남겨두면, 다음 번에 비슷한 문제가 나왔을 때 훨씬 빠르게 처리할 수 있다.