API 연동이 실패할 때 에러 메시지는 대개 친절하지 않습니다. 잘못된 요청, 서명 불일치, 형식 오류처럼 넓은 말만 보여 주는 경우가 많아서, 짧고 반복 가능한 확인 순서가 있으면 원인을 훨씬 빨리 좁힐 수 있습니다.
1. 원본 JSON부터 먼저 검증하기
가장 먼저 실제 요청 본문을 JSON YAML 변환에 넣어 보세요.
이때 주로 볼 항목은 다음과 같습니다.
- 마지막 쉼표
- 따옴표 종류
- 누락된 쉼표
- 예상과 다른 중첩 구조
2. 인코딩 경계 확인하기
문제가 JSON 자체가 아니라 문자열 포장 방식일 수도 있습니다.
자주 보는 사례는 아래와 같습니다.
- Base64 값이 다른 변형으로 해석된 경우
- URL 파라미터가 두 번 인코딩된 경우
- UTF-8 텍스트가 다른 문자셋으로 처리된 경우
이럴 때는 URL 인코딩 디코딩와 JWT 디코더를 함께 보면 빠릅니다.
3. 시간값 해석 맞추기
타임스탬프는 작은 차이로 큰 오류를 만듭니다.
- 초 단위인지 밀리초 단위인지
- UTC 기준인지 로컬 시간 기준인지
- 만료 시간이 이미 지났는지
숫자만 보지 말고, 시스템이 어떤 단위를 기대하는지 먼저 확인하세요.
4. 토큰 클레임 확인하기
인증 문제라면 JWT 내용을 열어 아래 항목을 확인합니다.
- exp 만료 여부
- aud 대상 값 일치 여부
- iss 와 sub 값 정확성
5. 정상 요청과 실패 요청 비교하기
겉보기에는 비슷해도 실제로는 필드명 대소문자, null 처리, 빈 문자열 차이 같은 작은 요소 때문에 실패하는 경우가 많습니다.
정상 요청 하나와 실패 요청 하나를 나란히 두고 비교하면 원인이 빨리 보입니다. 이런 비교에는 텍스트 비교도 도움이 됩니다.
팀 차원에서 습관으로 만들기
PR 템플릿이나 배포 체크리스트에 아래 다섯 줄만 넣어도 반복 사고를 줄일 수 있습니다.
- JSON 검증 완료
- 인코딩 확인 완료
- 시간값 해석 확인 완료
- 토큰 클레임 확인 완료
- 예시 요청과 응답 첨부
좋은 디버깅은 감으로 찾는 것이 아니라, 좁혀 가는 순서를 만드는 데서 시작합니다.