How do I troubleshoot CORS errors from my API Gateway API?

Short description

Cross-origin resource sharing (CORS) errors occur when a server doesn't return the HTTP headers that the CORS standard requires. 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: You must configure CORS at the resource level. Use API Gateway configurations or backend integrations, such as AWS Lambda.

Resolution

In addition to the No 'Access-Control-Allow-Origin' header present CORS error, you can use the following procedure to troubleshoot all CORS errors. Other CORS errors include Method not supported under Access-Control-Allow-Methods header and No 'Access-Control-Allow-Headers' headers present.

The No 'Access-Control-Allow-Origin' header present error can occur for the following reasons:

• You didn't configure the API with an OPTIONS method that returns the required CORS headers.
• You didn't configure other method types, such as GET, PUT, or POST, to return the required CORS headers.
• You didn't configure an API with proxy integration or non-proxy integration to return the required CORS headers.
• For private REST APIs, the incorrect invoke URL is called. Or, the traffic isn't routed to the interface virtual private cloud (VPC) endpoint.

Confirm the cause of the error

Take the following actions:

• When you invoke your API, create an HTTP Archive (HAR) file. Then, check the parameter headers that are returned in the API response to confirm the cause of the file error.
• Use the developer tools in your browser to check the request and response parameters from the failed API request.

Configure CORS on the failed API resource

For REST APIs

Follow the instructions in Turn on CORS on a resource using the API Gateway console.

For HTTP APIs

Follow the instructions in Configuring CORS for an HTTP API.

When you configure CORS on your API resource, select the following options:

For Gateway responses, select DEFAULT 4XX and DEFAULT 5XX. When you select DEFAULT 4XX and DEFAULT 5XX, 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, then API Gateway still responds with a 403 "Missing Authentication Token" error.

For Access-Control-Allow-Methods, if OPTIONS isn't already selected, then select it and all other methods that are available to CORS requests, such as GET, PUT, and POST. The API Gateway console configures the OPTIONS method's 200 response with the required Access-Control-Allow headers and overwrites existing values in the reconfigured resource.

Configure your REST API integrations to return the required CORS headers

To return the required CORS headers in its response, configure your backend Lambda function or HTTP server. You must include allowed domains 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 that your API's backend returns. In a proxy integration, API Gateway forwards the backend response directly to the client.

For non-proxy integrations, you must manually set up an integration response in API Gateway to return the required CORS headers. Use the API Gateway console to configure CORS because the console automatically adds the required CORS headers to the configured resource.

(For private REST APIs only) Check the private DNS setting of your interface endpoint

For private REST APIs, determine whether private DNS is activated on the associated interface VPC endpoint.

Private DNS is activated

Use the private DNS name to invoke your private API from within your Amazon Virtual Private Cloud (Amazon VPC).

Private DNS isn't activated

You must manually route traffic from the invoke URL to the IP addresses of the VPC endpoint. Use the following invoke URL (Route53 alias):

https://{rest-api-id}-{vpce-id}.execute-api.{region}.amazonaws.com/{stage}

Note: Replace rest-api-id, region, vpce-id, and stage with your API values. For more information, see How to invoke a private API.

If private DNS isn't activated, then you can't use endpoint-specific public DNS names to access your private API from within your Amazon VPC. Also. you can't use the Host header option because requests from a browser don't allow Host header modification.

For private APIs, 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 don't reach your API.

Note: Make sure that authorization is turned off in the OPTIONS method of your API.

Related information

Testing CORS

Turn on CORS on a resource using the API Gateway import API