GUIDE - Updated 2026-05-15
API 디버깅에서 JSON 오류를 확인하는 순서
API JSON 파싱 오류를 status code, Content-Type, response body, JSON validate 순서로 확인하는 실무 절차.
Open JSON Error Doctor핵심 요약
API JSON 오류는 JSON 문법만 보지 말고 HTTP 응답부터 확인해야 합니다. status code, Content-Type, 실제 response body를 본 뒤에 JSON validate를 해야 원인을 빠르게 좁힐 수 있습니다. Unexpected token <는 특히 JSON 문법보다 HTML 응답 문제일 가능성이 큽니다.
왜 중요한가
프론트엔드에서 response.json()이 실패하면 JSON 파일이 틀렸다고 생각하기 쉽습니다. 하지만 실제 원인은 로그인 HTML, 404 페이지, 서버 오류 페이지, 프록시 fallback인 경우가 많습니다. 확인 순서를 정해두면 같은 오류를 반복해서 디버깅하지 않아도 됩니다.
기본 개념
| 확인 항목 | 보는 이유 |
|---|---|
| Request URL | 올바른 API로 갔는지 확인 |
| Status code | 인증, 404, 500 문제 구분 |
| Content-Type | JSON인지 HTML인지 확인 |
| Response body | 실제 파싱 대상 확인 |
| JSON validate | 문법 오류 위치 확인 |
비교표
| 증상 | 먼저 의심할 것 | 다음 행동 |
|---|---|---|
Unexpected token < | HTML 응답 | Response 첫 글자 확인 |
Unexpected end | 빈 응답 또는 잘린 응답 | body length 확인 |
Unexpected token } | trailing comma 등 문법 오류 | validate |
| 로컬만 성공 | proxy/base URL 차이 | 환경별 URL 비교 |
실무 적용 방법
- Network 탭에서 실패한 요청을 찾습니다.
- Request URL, method, status code를 확인합니다.
- Content-Type이
application/json인지 봅니다. - response body를 복사해 JSON Error Doctor에 넣습니다.
- 문법 문제인지, 응답 형식 문제인지 분리합니다.
- 서버 오류도 JSON 형태로 반환하도록 개선합니다.
예제
디버깅용 코드:
const response = await fetch("/api/profile");
const text = await response.text();
console.log(response.status, response.headers.get("content-type"), text.slice(0, 200));
본문이 HTML이면 response.json()을 고치는 것이 아니라 API 라우팅, 인증, 서버 오류를 확인해야 합니다.
관련 도구
- JSON Error Doctor: 실제 response body가 JSON인지 검사할 수 있습니다.
관련 에러
- Unexpected token < in JSON at position 0
- API 응답이 JSON이 아니라 HTML일 때
- JSON Unexpected token 오류
- JSON unexpected end of input
관련 가이드
업데이트 날짜
2026-05-15