CORS 오류, 응답 헤더부터 바꾸기 전에 확인할 것

외부 API를 호출했는데 콘솔에 CORS 관련 오류가 보인다면, 응답 헤더를 바로 바꾸기 전에 오류의 사유부터 읽어보세요. 브라우저가 응답을 스크립트에 공개하지 않는 경우도 있고, 요청 자체가 네트워크나 프로토콜 단계에서 실패한 경우도 있습니다. 같은 빨간색 오류라도 진단의 출발점은 달라집니다.

1. 응답 접근 차단과 요청 실패를 구분하세요

MDN은 CORS를 HTTP 헤더를 통해 다른 출처의 접근 허용 여부를 알리는 메커니즘으로 설명합니다. 브라우저의 fetch나 XMLHttpRequest로 교차 출처 응답을 읽으려면 상황에 맞는 CORS 응답 설정이 필요합니다. 출처는 스킴, 호스트, 포트의 조합으로 구분합니다. CORS 개요

하지만 CORS 관련 메시지가 언제나 서버 헤더 설정만을 뜻하는 것은 아닙니다. 특히 CORS request did not succeed 사유는 네트워크 또는 프로토콜 수준의 연결 실패를 나타낼 수 있습니다. DNS, 연결 거부, TLS 등의 문제인지 네트워크 패널에서 함께 확인해야 합니다. 이 오류 사유의 설명

편집팀은 먼저 실패한 요청의 주소와 콘솔에 표시된 정확한 사유를 기록하는 방식을 권합니다. 오류 이름만 보고 “서버 장애” 또는 “헤더 누락”으로 결론 내리지 않는 것이 핵심입니다.

2. 사전 요청과 실제 요청을 따로 보세요

일부 교차 출처 요청에서는 브라우저가 실제 요청 전에 OPTIONS 사전 요청(preflight)을 보냅니다. 이 단계에서 메서드와 헤더 등의 허용 여부를 확인합니다. 사전 요청이 성공했는지와 실제 요청이 성공했는지는 나누어 살펴봐야 합니다.

GET, HEAD, POST 같은 메서드 조건과 허용된 헤더·콘텐츠 유형 등의 조건을 만족하는 요청은 사전 요청이 생략될 수 있습니다. 다만 POST이면 무조건 단순 요청이라고 이해하면 안 됩니다. 세부 조건은 공식 문서에서 실제 요청과 대조하세요. 단순 요청과 사전 요청

사전 요청이 없다고 응답을 자유롭게 읽을 수 있는 것도 아닙니다. 실제 응답의 CORS 허용 조건은 별도로 충족해야 합니다. 요청 형태를 억지로 바꾸거나 no-cors를 지정하는 일을 일반적인 해결책으로 삼지 않는 편이 좋습니다.

3. 콘솔의 사유에 맞춰 조사 범위를 좁히세요

MDN의 오류 목록은 응답 헤더 누락, 출처 불일치, 사전 요청 실패 등 여러 사유를 구분합니다. 먼저 지금 발생한 메시지와 일치하는 항목을 찾습니다. CORS 오류 목록

• 요청 자체가 실패했다면 주소·스킴·포트와 연결 상태를 확인합니다.
• 응답은 왔지만 읽기가 차단됐다면 콘솔의 사유와 실제 응답 헤더를 대조합니다.
• 사전 요청에서 실패했다면 OPTIONS 응답과 뒤따르는 실제 요청의 유무를 나누어 확인합니다.
• 서버를 직접 관리하지 않는다면 제공자의 브라우저 호출 지원 여부와 공식 연동 방식을 확인합니다.

위 순서는 편집팀이 제안하는 진단 흐름입니다. 실제 원인은 해당 요청과 서비스의 조건에서 확인해야 합니다. 타사 서버의 정책을 브라우저 보안 설정 해제로 해결하려고 하거나, 민감한 요청을 임의의 공개 중계 서비스로 보내지는 마세요.

4. 다음 사람에게 전달할 짧은 기록

도움을 요청할 때는 오류 화면 전체보다 필요한 정보가 무엇인지 먼저 정리해 보세요. 요청한 주소에서 민감한 쿼리 값은 가리고, 메서드, 정확한 오류 사유, 사전 요청 유무, 관찰한 상태를 적습니다. 토큰·쿠키·개인정보가 포함된 요청 헤더를 그대로 공유하지 않도록 주의하세요.

이 글은 공식 문서에 따른 진단 기준을 설명합니다. 특정 서버의 장애를 재현하거나 실제 헤더를 변경한 시험 결과는 아닙니다. 중요한 것은 CORS라는 단어 하나로 원인을 확정하지 않고, 실패가 발생한 단계를 먼저 찾는 일입니다.