API 요청이 CORS 에러로 막힐 때 확인 순서

프론트엔드에서 API를 호출할 때 CORS 에러가 나면, 보통 즉시 백엔드로 가서 Access-Control-Allow-Origin 헤더를 추가하려고 한다. 하지만 실제로는 단순한 응답 헤더 문제일 수도 있고, 요청 자체의 형식이 잘못되었을 수도 있다. 우선 실제로 서버가 뭘 응답하고 있는지 확인해야 한다.

curl로 실제 응답 확인

APIspec 문서의 주소를 curl로 직접 호출해보자. 이렇게 하면 브라우저가 요청을 차단하지 않으므로, 서버가 실제로 뭘 응답하는지 알 수 있다.

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

결과에서 보야할 것들:

• HTTP/ 뒤의 상태 코드 (200이 정상, 401이면 인증 필요, 403이면 권한 부족)
• Access-Control-Allow-Origin: 헤더가 있는지
• 응답 body에 실제 데이터가 있는지, 아니면 에러 메시지인지

로컬과 운영 환경 비교

API가 로컬 개발 서버에서는 CORS를 허용하지만 운영 서버에서는 제한하는 경우가 많다. 이는 보통 환경 변수나 설정 파일에서 허용 도메인을 다르게 설정한 결과다.

로컬 개발 환경의 API 응답과 운영 환경의 API 응답을 나란히 놓고 비교해서:

• CORS 헤더가 둘 다 있는지
• 허용되는 도메인이 현재 프론트엔드 도메인을 포함하는지

확인해보자.

상태 코드와 응답 확인

CORS 에러가 나기 전에 서버 에러가 있을 수 있다. 상태 코드가 200이 아니라면:

• 4xx 에러: 요청이 잘못됐거나 권한이 없음 (보통 인증 토큰이 없거나 만료됨)
• 5xx 에러: 서버에 문제가 있음

CORS 에러는 상태 코드가 100~599 중 하나인 경우에도 발생할 수 있다. 즉, 요청이 서버에 도달했지만 응답 헤더가 없거나 잘못되었다는 뜻이다.

요청 헤더와 인증 확인

API가 인증을 요구한다면, 요청에 적절한 토큰이나 헤더를 포함해야 한다. curl로 헤더를 추가해서 테스트해보자:

curl -i -H "Authorization: Bearer YOUR_TOKEN" 'https://example.com/api/items'

프론트엔드에서도 같은 방식으로 헤더를 보내고 있는지 확인하자. 만약 프론트엔드에서는 헤더를 보냈는데 curl 테스트에서는 빼먹었다면, 인증 문제일 수도 있다.

최종 확인: 작은 변경으로 검증

API 설정에서 한 가지씩만 바꿔보자:

1. CORS 설정을 열어서 모든 도메인을 허용하고 프론트엔드 요청이 통과하는지 확인
2. curl로 다시 테스트해서 응답이 같은지 확인
3. 다시 원래 설정으로 돌리고, 필요한 도메인만 명시적으로 허용

한 번에 여러 설정을 바꾸면 뭐가 원인인지 파악하기 어려워진다.