API 인증 상태를 응답 코드와 본문으로 빠르게 진단하기

API 작업할 때 인증 문제가 생기면, 화면에만 집중하면 원인을 놓치기 쉽다. 대신 curl로 API를 직접 호출해서 상태 코드와 응답을 확인하는 게 훨씬 빠르다.

첫 번째: 상태 코드로 원인 좁히기

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

응답 헤더의 상태 코드를 먼저 본다.

• 200 OK: 요청이 성공했다. 응답 본문을 확인해서 실제 데이터가 맞는지 봐야 한다
• 400 Bad Request: 요청 형식이 잘못됐다. 파라미터나 요청 본문을 확인
• 401 Unauthorized: 인증 정보가 없거나 유효하지 않다. 쿠키나 Authorization 헤더 확인
• 403 Forbidden: 인증은 됐지만 해당 리소스에 접근 권한이 없다. 사용자 권한 확인
• 500 Internal Server Error: 서버 에러. 서버 로그 확인 필요

두 번째: 응답 본문의 에러 메시지 확인

상태 코드만으로는 부족하면, 응답 본문의 에러 메시지를 자세히 읽는다.

curl -s 'https://example.com/api/items?page=1' | jq '.'

jq 없이 원본 JSON을 보고 싶다면:

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

응답에 "error": "Invalid token" 같은 메시지가 있으면, 토큰 검증이 실패한 거다. "error": "User not found"면 사용자 조회 실패다. 에러 메시지가 구체할수록 원인 찾기가 쉽다.

세 번째: 정상 상태와 비교하기

로컬 개발 환경이나 다른 테스트 계정으로 같은 API를 호출해봐서 정상 응답과 비교한다.

# 정상 상태
curl -s 'https://localhost:3000/api/items?page=1' | jq '.data | length'

# 배포 환경
curl -s 'https://example.com/api/items?page=1' | jq '.data | length'

응답 구조나 데이터 개수가 달라면, 쿼리 로직이나 데이터베이스 상태에 차이가 있을 수 있다.

넷째: 쿠키 또는 인증 헤더 확인

인증이 필요한 API라면, 쿠키나 Authorization 헤더를 제대로 보내고 있는지 확인해야 한다.

# 쿠키 전달
curl -i -b 'session=abc123xyz' 'https://example.com/api/items?page=1'

# Bearer 토큰 전달
curl -i -H 'Authorization: Bearer abc123xyz' 'https://example.com/api/items?page=1'

쿠키나 토큰을 추가하면 인증이 성공하는지 확인한다. 만약 여전히 401이 나오면, 토큰 자체가 유효하지 않거나 만료된 걸 수 있다.

확인 체크리스트

1. 상태 코드 확인 (200, 401, 403, 500 등)
2. 응답 본문의 에러 메시지 읽기
3. 로컬이나 다른 환경과 비교해서 응답 형식이 같은지 확인
4. 필요하면 쿠키나 Authorization 헤더를 명시적으로 추가해서 테스트
5. 여전히 안 되면 서버 로그 확인

이렇게 단계적으로 확인하면, API 인증 문제를 빠르게 진단하고 해결할 수 있다.