API 응답이 이상할 때 진단 순서

API 문제는 서버와 클라이언트 사이의 계약 위반이다. 요청 형식, 응답 형식, 에러 처리가 맞지 않으면 서로 이해하지 못한다.

요청 헤더와 body 확인

실제로 어떤 요청을 보내고 있는지 본다.

# curl로 정확히 재현
curl -i -X POST https://example.com/api/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "John", "email": "[email protected]"}'

브라우저 개발자 도구의 Network 탭에서도 요청을 복사해서 curl로 재현할 수 있다. (Copy as cURL)

응답 코드 확인

curl -i https://example.com/api/users

응답의 첫 줄이 중요하다:

• 200: 성공
• 201: 리소스 생성 성공
• 400: 잘못된 요청
• 401: 인증 필요
• 403: 권한 없음
• 404: 리소스 없음
• 500: 서버 에러

401이나 403이 나면, 인증 토큰이나 권한을 확인해야 한다.

응답 body 파싱

curl -s https://example.com/api/users | jq .

JSON이 제대로 형식화되었는지, 필드가 예상과 일치하는지 본다.

# 특정 필드만 보기
curl -s https://example.com/api/users | jq '.data[].id'

# 전체 구조 파악
curl -s https://example.com/api/users | jq 'keys'

Content-Type 확인

curl -i https://example.com/api/users | grep -i content-type

Response 헤더에서 Content-Type: application/json이 있어야 한다. 없으면 클라이언트가 제대로 파싱하지 못한다.

타임스탬프와 시간대

API에서 반환하는 날짜가 ISO 8601 형식인지, timezone이 명시되어 있는지 확인한다.

curl -s https://example.com/api/events | jq '.createdAt'
# "2026-06-01T15:30:00Z" (좋음)
# "2026-06-01 15:30:00" (ambiguous, 타임존 없음)

클라이언트에서 파싱할 때 new Date(createdAt)이 제대로 인식되지 않을 수 있다.

페이지네이션 응답

페이지 번호, 크기, 전체 개수 등이 제대로 반환되는지 본다.

curl -s 'https://example.com/api/users?page=1&limit=10' | jq '{data, pagination}'

API 문서와 응답 형식이 일치하지 않으면, 클라이언트는 "다음 페이지가 있는가?"를 판단할 수 없다.

빈 응답 처리

# 데이터가 없을 때
curl -s 'https://example.com/api/users?status=inactive' | jq .

# [] 인가? {data: []} 인가? null 인가?

빈 배열, 빈 객체, null이 모두 다르고, 클라이언트는 각각 다르게 처리해야 한다.

에러 응답 형식

curl -s -X POST https://example.com/api/users \
  -d '{"email": "invalid-email"}' | jq .

# {error: "Invalid email"} 인가?
# {message: "Validation failed"} 인가?
# {errors: [{field: "email", message: "..."}, ...]} 인가?

API가 반환하는 에러 형식이 정해지면, 클라이언트에서 그에 맞게 처리한다.

서버 로그 확인

# API 요청이 실제로 도착했는지
sudo journalctl -u api-service -f

# 또는 Docker 로그
docker logs -f <api_container>

에러 로그가 있으면, 서버에서 무엇이 잘못됐는지 알 수 있다.

응답 시간 측정

time curl -s https://example.com/api/users > /dev/null

# 또는 더 자세히
curl -w "@curl-format.txt" -o /dev/null -s https://example.com/api/users

응답이 너무 오래 걸리면, 쿼리가 느리거나 네트워크 문제가 있을 수 있다.