재고 API를 호출했는데 JSON 파서가 첫 글자 <에서 멈췄다면, 그 요청의 응답을 먼저 확인하세요. 주소가 잘못돼 앱의 HTML 화면으로 연결됐거나, 인증 만료 뒤 로그인 페이지에 도착했을 수 있습니다. 첫 글자는 단서이고 실제 응답의 상태, 형식, 최종 경로를 함께 보면 수정할 계층을 좁힐 수 있습니다.
같은 파싱 오류를 서로 다른 응답으로 분리하기
| 응답에서 확인한 값 | 다음 확인 |
|---|---|
| 401 또는 403과 HTML | 인증·권한 흐름과 오류 응답을 만든 계층을 찾습니다. |
| 200과 HTML, 최종 경로가 로그인 화면 | 요청이 리디렉션되었는지 확인하고 API 호출의 인증 만료 계약을 점검합니다. |
| 200과 HTML, 최종 경로가 요청 경로와 같음 | API 라우팅·SPA 대체 응답·프록시·서비스 워커에서 본문이 바뀌었는지 확인합니다. |
| 204 또는 205 | 응답 본문이 없어도 되는 API인지 확인합니다. 아래 재고 예제에는 목록 본문이 필수입니다. |
| 200과 JSON 형식, 파서 실패 | 본문 문법과 Content-Encoding을 나누어 점검합니다. |
| 200과 파싱 성공, 필요한 필드 누락 | 응답 구조와 타입을 앱의 데이터 계약과 대조합니다. |
개발자 도구에서 한 요청만 따라가기
- 네트워크 패널에서 실패한 API 요청을 선택합니다. 요청 경로와 메서드, 상태 코드, 응답의 Content-Type을 확인합니다.
- 리디렉션 체인과 최종 경로를 확인합니다. fetch에서 이미 따라간 응답의
redirected와url은 사후 관찰값입니다. 리디렉션이 허용되지 않는 API라면 요청 시점의redirect: 'error'정책을 검토하세요. - 응답 본문은 권한 있는 테스트 환경에서 형식을 확인하는 데만 사용합니다. 운영 로그에는 상태, 형식 분류, 안전한 경로와 추적 ID만 남기고 토큰, URL 쿼리, 로그인 HTML 전체는 기록 대상에서 제외합니다.
fetch는 404 같은 HTTP 오류에도 응답을 반환할 수 있으므로 상태를 먼저 확인합니다. 브라우저에서 CORS나 네트워크 문제로 요청 자체가 거절되면 검사할 Response가 없을 수 있습니다. 이 경우에는 요청 오류 단계에서 다루고, no-cors로 읽을 수 없는 응답을 만들면 JSON을 확인할 수 없습니다.
재고 목록 응답을 읽는 예제
예제의 성공 조건은 application/json으로 제공되는 items 배열이며 항목마다 이름과 0 이상의 안전한 정수 재고가 필요합니다. 헤더의 charset은 별도로 떼어냅니다. 프로젝트가 application/problem+json 같은 다른 형식을 계약에 포함하면 상태별 허용 형식과 구조를 정의하세요.
async function readInventory(response) {
const status = response.status;
const media = (response.headers.get('content-type') ?? '')
.split(';')[0].trim().toLowerCase();
if (response.type === 'opaque' || response.type === 'opaqueredirect') {
return { kind: 'unreadable-response', status };
}
if (!response.ok) return { kind: 'http-error', status };
if (status === 204 || status === 205) {
return { kind: 'missing-body', status };
}
// 이 API의 응답 계약은 application/json으로 한정합니다.
if (media !== 'application/json') {
return { kind: 'unexpected-media', status, redirected: response.redirected };
}
let data;
try {
data = await response.json();
} catch (error) {
if (error.name === 'AbortError') throw error;
return {
kind: error instanceof SyntaxError ? 'invalid-json' : 'read-failed',
status,
};
}
if (!data || !Array.isArray(data.items) ||
!data.items.every(item => item &&
typeof item.name === 'string' &&
Number.isSafeInteger(item.stock) && item.stock >= 0)) {
return { kind: 'invalid-shape', status };
}
return { kind: 'ready', items: data.items };
}
호출자는 fetch 단계에서 네트워크 실패와 사용자 취소를 처리한 뒤 Response를 이 함수에 넘깁니다. 함수는 응답을 한 번 읽고 실패 종류만 반환합니다. 디버깅을 위해 같은 객체의 text()를 먼저 호출하면 이후 json()에서 이미 소비된 본문을 다시 읽을 수 없습니다.
로컬 HTTP 응답에서 관찰한 결과
2026년 11월 5일 Node.js v24.22.1에서 127.0.0.1의 임시 HTTP 서버에 실제 fetch 요청을 보냈습니다. 각 경로는 고정 응답을 반환했습니다.
| 테스트 응답 | 상태 | 관찰한 분류 |
|---|---|---|
| /ok | 200 | ready |
| /unauthorized | 401 | http-error |
| /fallback | 200 | unexpected-media |
| /empty | 204 | missing-body |
| /invalid | 200 | invalid-json |
| /shape | 200 | invalid-shape |
| /missing-type | 200 | unexpected-media |
| /read-error | 200 | read-failed |
| /redirect | 200 | unexpected-media |
/redirect는 302 뒤 /fallback의 200 HTML에 도착했고 리디렉션 표시가 참이었습니다. /read-error는 평문 본문에 gzip이라고 선언해 읽기 오류로 분류했습니다. 브라우저 CORS, 실제 로그인, 프록시 및 서비스 워커 재현은 이 실험 범위 밖입니다. 운영에서 같은 현상이 보이면 네트워크 패널과 해당 계층의 로그로 원인을 확인하세요.
응답을 만든 계층에 맞춰 수정하기
API 경로에서만 HTML 대체 화면이 나온다면 서버 라우팅과 프록시 순서를 확인합니다. 배포 직후 이전 응답이 반복되면 서비스 워커와 캐시 점검으로 이어가세요. 429는 요청 제한과 Retry-After에서 다루고, 정상 JSON의 필드가 잘못된 경우는 Dart JSON 모델 검증을 참고하세요. Android의 선언 파일을 확인하는 경우는 App Links 검증에 별도 절차가 있습니다.
확인한 문서
2026년 11월 5일 다음 원문을 확인했습니다.