API

외부 API 연동이 자꾸 실패할 때 디버깅 방법

외부 API와 연동할 때는 인증 토큰, 요청 형식, 타임아웃 설정을 순서대로 확인해야 자주 실패하는 이유를 찾을 수 있다.

2026년 6월 24일·1분 읽기

제3자 API와 연동하다 보면 문제가 생기는데, 로컬에서는 잘 되다가 배포에서 안 되는 경우가 많다.

인증 토큰 확인

가장 먼저 확인할 게 인증 토큰이다. 배포 환경의 API 키가 정확한지, 유효 기간이 남았는지 본다.

curl -X GET 'https://external-api.com/v1/status' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -w "\n%{http_code}\n"

401이나 403이 나오면 토큰 문제다. 새 토큰을 발급받거나 기존 토큰을 다시 확인해본다.

JSON 필드 이름, 인코딩, Content-Type 헤더가 맞는지 확인한다. 외부 API는 엄격해서 조금만 달라도 400 에러를 던진다.

curl -X POST 'https://external-api.com/v1/items' \
  -H "Content-Type: application/json" \
  -d '{"name":"test","value":123}'

로컬에서 빠르더라도 배포 환경의 네트워크 지연으로 타임아웃이 날 수 있다. 타임아웃 값을 충분히 크게 설정하고, 재시도 로직을 넣는다.

오류를 기록할 때 "API 요청 실패 (3번 재시도), 최종 상태코드: 504, 소요 시간: 15초" 같은 세부 정보를 남기면 나중에 패턴을 찾을 수 있다.