API 호출 시 User-Agent 헤더로 인한 응답 차이 정리

1. 상황 요약

대상: https://aaaaa.com/ai/xxx-token 같은 외부 API를 PHP에서 POST로 호출
증상: 같은 URL·같은 Body로 요청해도, User-Agent를 넣었을 때만 JSON이 오고, 빼면 HTML이 옴
원인: 서버(또는 앞단 CDN)가 User-Agent 값으로 “API 클라이언트” vs “일반 브라우저”를 구분하고, 그에 따라 다른 응답을 내려줌

2. User-Agent란?

정의: HTTP 요청 헤더 중 하나로, “이 요청을 보낸 클라이언트(브라우저, 앱, 봇 등)가 무엇인지”를 나타내는 문자열
예시

서버/CDN은 이 값을 보고 “일반 사용자 브라우저”인지 “우리 API를 쓰는 클라이언트”인지 구분할 수 있다.

3. 왜 User-Agent에 따라 응답이 달랐나?

User-Agent를 넣었을 때→ 서버가 “API 클라이언트”로 인식 → 해당 API용 JSON 응답
User-Agent를 빼거나 일반 브라우저 값일 때→ “일반 웹 접속”으로 간주 → SPA용 index HTML (또는 메인 페이지 HTML) 반환

즉, 같은 URL이라도 “누가 요청했는지”에 따라 라우팅/캐시가 달라지는 구조였다.

그래서 Accept: application/json, Content-Type: application/json만 있고 User-Agent가 없으면 여전히 HTML이 올 수 있었고, User-Agent를 추가한 뒤에만 JSON이 안정적으로 옴.

4. 코드에서 발생한 문제점

4-1. User-Agent 누락 시

증상: rawResponse에 API JSON이 아니라 <!doctype html>... 로 시작하는 HTML이 들어옴
원인: 요청 헤더에 User-Agent가 없어 서버가 “일반 브라우저”로 처리
해결: API를 호출하는 쪽(cURL이든 stream_context이든)에 반드시 서버가 인정하는 User-Agent 값을 넣어야 함(예: User-Agent: MyApiClient/1.0)

4-2. cURL 사용 시 헤더 구성

필수: Authorization, User-Agent
권장: Content-Type: application/json, Accept: application/json(동작은 User-Agent만으로 될 수 있지만, 관례와 향후 변경 대비를 위해 두는 것이 좋음)
주의: User-Agent를 제거하면 다시 HTML이 오는 것이 확인되었으므로, 이 헤더는 제거하면 안 됨

4-3. cURL이 없을 때 쓰는 `stream_context` (file_get_contents) 경로

header 옵션은 한 번에 하나의 문자열로 넘겨야 함
여러 헤더를 넣을 때는 문자열을 . 로 이어붙여서 하나의 문자열로 만들어야 함

잘못된 예 (문자열 연결 실수):

php

'header' => "Authorization: Bearer " . trim($token) . "\r\n" .
  "Content-Type: application/json\r\n" ,   // 여기서 문자열 끝
  "Accept: application/json\r\n" .         // 이 줄은 연결되지 않음 (앞에 . 없음)
  "User-Agent: MyApiClient/1.0\r\n"

두 번째 줄 끝에 ,만 있고 .가 없어서 세 번째·네 번째 줄이 실제 header 문자열에 포함되지 않을 수 있음
그 결과 Authorization만 전달되고, Content-Type / Accept / User-Agent가 빠진 요청이 나갈 수 있음

올바른 예:

php

'header' => "Authorization: Bearer " . trim($token) . "\r\n" .
            "Content-Type: application/json\r\n" .
            "Accept: application/json\r\n" .
            "User-Agent: MyApiClient/1.0\r\n"

모든 헤더가 . 로 이어진 하나의 문자열이 되도록 해야 함

API 호출 시 User-Agent 헤더로 인한 응답 차이 정리

1. 상황 요약

2. User-Agent란?

3. 왜 User-Agent에 따라 응답이 달랐나?

4. 코드에서 발생한 문제점

4-1. User-Agent 누락 시

4-2. cURL 사용 시 헤더 구성

4-3. cURL이 없을 때 쓰는 `stream_context` (file_get_contents) 경로

4-4. 정리

이 글이 도움이 되셨나요?

관련 포스트

댓글

1. 상황 요약

2. User-Agent란?

3. 왜 User-Agent에 따라 응답이 달랐나?

4. 코드에서 발생한 문제점

4-1. User-Agent 누락 시

4-2. cURL 사용 시 헤더 구성

4-3. cURL이 없을 때 쓰는 stream_context (file_get_contents) 경로

4-4. 정리

이 글이 도움이 되셨나요?

관련 포스트

댓글

4-3. cURL이 없을 때 쓰는 `stream_context` (file_get_contents) 경로