API Gateway CORS 오류 완전 해결 가이드: 콘솔 설정부터 Lambda 응답 헤더까지
프론트엔드에서 API Gateway를 호출했을 때 CORS 오류 가 발생하면, 대부분의 엔지니어는 콘솔에서 'Enable CORS' 버튼 하나만 누르면 해결된다고 생각한다. 실제로는 그 버튼이 절반의 작업만 처리하고, 나머지 절반은 Lambda 함수 응답에서 직접 헤더를 반환해야 한다 — 이 사실을 모르면 콘솔 설정 후에도 동일한 오류가 반복된다. TL;DR — API Gateway CORS 오류 핵심 요약 구분 내용 문제 원인 브라우저 preflight OPTIONS 요청에 CORS 헤더 누락, 또는 실제 응답에 헤더 없음 콘솔 설정 역할 OPTIONS 메서드 Mock 응답에 CORS 헤더 추가 + 배포 필요 Lambda 역할 GET/POST 등 실제 메서드 응답에 직접 CORS 헤더 포함해야 함 필수 헤더 Access-Control-Allow-Origin, Access-Control-Allow-Headers, Access-Control-Allow-Methods 자주 놓치는 것 콘솔 설정 후 Stage 재배포 누락 CORS가 API Gateway에서 동작하는 방식 브라우저는 크로스 오리진 요청을 보내기 전에 먼저 preflight 요청 을 OPTIONS 메서드로 전송한다. 서버가 이 OPTIONS 요청에 올바른 CORS 헤더로 응답해야 브라우저가 실제 요청을 허용한다. API Gateway에서 이 흐름을 이해하지 못하면 설정이 반쪽짜리가 된다. API Gateway REST API에서 CORS는 두 개의 독립된 레이어에서 처리된다. 첫 번째는 OPTIONS preflight — API Gateway가 Lambda를 호출하지 않고 Mock 통합으로 직접 응답한다. 두 번째는 실제 메서드(GET, POST 등) 응답 — Lambda 함수가 응답 본문과 함께 CORS 헤더를 직접 ...