How do I troubleshoot CORS errors from my API Gateway API?
I get the error "No 'Access-Control-Allow-Origin' header is present on the requested resource" when I try to invoke my Amazon API Gateway API. How do I troubleshoot this error and other CORS errors from API Gateway?
Cross-Origin Resource Sharing (CORS) errors occur when a server doesn’t return the HTTP headers required by the CORS standard. To resolve a CORS error from an API Gateway REST API or HTTP API, you must reconfigure the API to meet the CORS standard.
Note: CORS must be configured at the resource level and can be handled using API Gateway configurations or backend integrations, such as AWS Lambda.
The following example procedure shows how to troubleshoot the No ‘Access-Control-Allow-Origin’ header present CORS error. However, you can use a similar procedure to troubleshoot all CORS errors. For example: Method not supported under Access-Control-Allow-Methods header errors and No ‘Access-Control-Allow-Headers’ headers present errors.
Note: The No 'Access-Control-Allow-Origin' header present error can occur for any of the following reasons:
- The API isn't configured with an OPTIONS method that returns the required CORS headers.
- Another method type (such as GET, PUT, or POST) isn't configured to return the required CORS headers.
- An API with proxy integration or non-proxy integration isn't configured to return the required CORS headers.
- (For private REST APIs only) The incorrect invoke URL is called, or the traffic isn't being routed to the interface virtual private cloud (VPC) endpoint.
Confirm the cause of the error
There are two ways to confirm the cause of a CORS error from API Gateway:
- Create an HTTP Archive (HAR) file when you invoke your API. Then, confirm the cause of the error in the file by checking the headers in the parameters returned in the API response.
- Use the developer tools in your browser to check the request and response parameters from the failed API request.
Configure CORS on your API resource that’s experiencing the error
For REST APIs
Follow the instructions to Turn on CORS on a resource using the API Gateway console.
For HTTP APIs
Follow the instructions in Configuring CORS for an HTTP API.
Important: If you configure CORS for an HTTP API, then API Gateway automatically sends a response to preflight OPTIONS requests. This response is sent even if there isn't an OPTIONS route configured for your API. For a CORS request, API Gateway adds the configured CORS headers to the response from an integration.
While configuring CORS on your API resource, make sure that you do the following:
- For Gateway Responses for <api-name> API, choose the DEFAULT 4XX and DEFAULT 5XX check boxes.
Note: When you select these default options, API Gateway responds with the required CORS headers, even when a request doesn't reach the endpoint. For example, if a request includes an incorrect resource path, API Gateway still responds with a 403 "Missing Authentication Token" error.
- For Methods, choose the check box for the OPTIONS method, if it isn't already selected. Also, choose the check boxes for all of the other methods that are available to CORS requests. For example: GET, PUT, and POST.
Note: Configuring CORS in the API Gateway console adds an OPTIONS method to the resource if one doesn’t already exist. It also configures the OPTIONS method's 200 response with the required Access-Control-Allow-* headers. If you already configured CORS using the console, configuring it again overwrites any existing values.
Configure your REST API integrations to return the required CORS headers
- Allowed domains must be included in the Access-Control-Allow-Origin header value as a list.
- For proxy integrations, you can't set up an integration response in API Gateway to modify the response parameters returned by your API's backend. In a proxy integration, API Gateway forwards the backend response directly to the client.
- If you use a non-proxy integration, you must manually set up an integration response in API Gateway to return the required CORS headers.
Note: For APIs with a non-proxy integration, configuring CORS on a resource using the API Gateway console automatically adds the required CORS headers to the resource.
(For private REST APIs only) Check the private DNS setting of your interface endpoint
If private DNS is activated
If private DNS isn't activated
You must manually route traffic from the invoke URL to the IP addresses of the VPC endpoint.
Note: You must use the following invoke URL, whether private DNS is activated or not:
Make sure that you replace the values for api-id, region, and stage-name with the required values for your API. For more information, see How to invoke a private API.
Important: If CORS is configured when private DNS isn't activated, keep in mind the following limitations:
- You can't use endpoint-specific public DNS names to access your private API from within your Amazon VPC.
- You can't use the Host header option, because requests from a browser don't allow Host header manipulation.
- You can’t use the x-apigw-api-id custom header, because it initiates a preflight OPTIONS request that doesn't include the header. API calls that use the x-apigw-api-id header won’t reach your API.