외부 API 연동할 때 권한 문제로 막힐 때 확인하는 것

외부 API를 연동하다 보면 갑자기 요청이 실패한다. 원인이 토큰 만료인지, 권한 부족인지, 아니면 요청 형식이 잘못된 건지 불명확할 때가 많다.

상황을 한 줄로 요약

"API 응답이 에러다"라고 하면 너무 모호하다. 어떤 에러인가. 401(Unauthorized)인가, 403(Forbidden)인가, 500(Internal Server Error)인가. 응답 메시지가 뭐라고 말하는가.

증거 모으기

API 요청 시 에러 메시지를 먼저 본다. 에러 메시지 자체가 문제를 직접 말해주는 경우가 많다.

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

curl로 직접 요청을 보내본다. 응답 헤더와 바디를 모두 확인한다. 내 요청이 정상적으로 전달되는지, 서버가 뭐라고 응답하는지 본다.

응답 body 확인

HTTP 상태 코드뿐만 아니라 응답 바디에 더 자세한 에러 정보가 있을 것이다. JSON으로 구조화된 에러 메시지를 읽는다.

가능한 원인들

• 토큰이 만료되었거나 없다
• 토큰은 있지만 권한이 부족하다
• 요청 파라미터가 잘못됐다
• API 서버가 다운되었다
• 요청하는 엔드포인트가 없다

가장 작은 실험

필수 파라미터만 넣어서 요청을 보낸다. 복잡한 필터나 옵션을 모두 빼고 기본 요청만 테스트한다.

인증 상태 확인

토큰이 정말로 유효한가. 만료 시간을 확인한다. 토큰 문자열이 완전하게 전달되는가. 토큰을 인코딩할 필요는 없는가.

통과 기준

상태 코드가 200대일 때, 응답 바디에 예상한 데이터가 있을 때. 응답을 받았다면 다음 단계로 넘어간다.

배운 점

같은 API 연동이 다시 필요할 때를 대비해 어떻게 문제를 해결했는지 기록해둔다. 다음에 비슷한 에러가 나오면 훨씬 빨리 찾을 수 있다.