외부 API 연동이 안 될 때 디버깅하는 방법

외부 API를 연동하다 보면 로컬에서는 잘 작동하던 코드가 프로덕션 서버에서 갑자기 작동하지 않는 경우가 있다. 보통의 원인은 세 가지다: 인증 토큰 만료, 요청 파라미터 오류, 응답 본문 파싱 실패다.

직접 API 요청해보기

먼저 애플리케이션을 통하지 않고 직접 curl로 API를 호출해본다. 그러면 로직 계층의 버그인지 네트워크 계층의 문제인지 빠르게 판단할 수 있다.

curl -i 'https://api.example.com/items?page=1' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

HTTP 상태 코드와 응답 본문을 확인한다. 401이 나오면 인증 문제, 400이 나오면 파라미터 문제, 500이 나오면 서버 문제일 가능성이 높다.

응답 본문 자세히 살펴보기

상태 코드가 200이라도 응답 본문이 예상한 형식이 아닐 수 있다. 특히 API 버전이 업데이트되었다면 응답 구조가 바뀌었을 수 있다.

curl -s 'https://api.example.com/items' \
  -H 'Authorization: Bearer YOUR_TOKEN' | jq .

JSON 응답을 pretty-print해서 보면 필드 이름, 자료형, 중첩 구조 같은 세부사항이 명확해진다. 만약 expected 필드가 없다면 API 문서를 다시 확인하거나 API 제공자에 문의해야 한다.

환경별 설정 차이 확인

외부 API는 대부분 환경별로 다른 엔드포인트와 토큰을 요구한다. 로컬 개발 환경과 프로덕션 서버의 환경 변수가 일치하는지 확인하자.

echo $API_TOKEN
echo $API_ENDPOINT
# 프로덕션 서버에서
ssh user@server 'echo $API_TOKEN'

특히 .env 파일이 배포 시 제대로 복사되었는지, 환경 변수가 올바르게 설정되었는지 확인한다. 많은 배포 자동화 도구들이 환경 변수를 누락시키곤 한다.

타이밍 문제와 타임아웃

상태 코드는 200이지만 응답이 없는 경우도 있다. 이는 대부분 연결 타임아웃이나 읽기 타임아웃 때문이다.

curl -m 30 'https://api.example.com/slow-endpoint'

-m 30으로 30초 타임아웃을 설정하고 테스트한다. 만약 30초 이내에 응답이 안 오면 API 서버가 느리거나 네트워크 연결이 불안정한 것이다.

요청과 응답을 기록하기

디버깅할 때는 정확히 무엇을 보냈고 무엇을 받았는지 기록해두는 것이 중요하다.

curl -v 'https://api.example.com/items' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"limit": 10}' 2>&1 | tee api-debug.log

-v 플래그를 쓰면 요청 헤더, 응답 헤더, 본문을 모두 볼 수 있다. 이 로그를 파일로 저장해두면 나중에 참고할 수 있다.

확인 순서 체크리스트

1. curl로 직접 API를 호출해본다. 상태 코드를 확인한다.
2. 응답 본문을 jq로 파싱해서 구조를 확인한다.
3. 로컬과 프로덕션의 환경 변수를 비교한다.
4. 타임아웃이 발생하는지 테스트한다.
5. 필요하면 애플리케이션 로그에서 추가 에러 메시지를 찾는다.

API 문제는 대부분 인증, 파라미터, 응답 형식 중 하나다. 이 세 가지를 체계적으로 확인하면 원인을 빠르게 찾을 수 있다.