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

Short description

CORS errors 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, API Gateway calls the incorrect invoke URL. Or, API Gateway doesn't route the traffic to the interface virtual private cloud (VPC) endpoint.

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

You can use the following resolution 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".

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.
• Use tools, such as cURL and Postman, to test the API and confirm that the endpoint returns a 200 status code.
  Note: If you didn't configure CORS headers for error responses, then non-200 responses might cause CORS errors. Troubleshoot and resolve non-200 status code errors first.

Configure CORS on the failed API resource

For REST APIs

Use the API Gateway console to activate CORS on a resource.

For HTTP APIs

Configure CORS for HTTP APIs in API Gateway.

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, select OPTIONS 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 the response, configure your backend Lambda function or HTTP proxy server. You must include allowed domains in the Access-Control-Allow-Origin header value as a list.

For proxy integrations, API Gateway forwards the backend response directly to the client. You can't set up an integration response in API Gateway to modify the response parameters that your API's backend returns.

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. The console automatically adds the required CORS headers to the configured resource.

Troubleshoot CORS errors for proxy and non-proxy integrations

No Access-Control-Allow-Origin header

If you didn't include allowed domains in your CORS settings, then you receive the following error message:

"No 'Access-Control-Allow-Origin' header present"

For proxy integrations, add the Access-Control-Allow-Origin header to your backend integration and include allowed domains.

For non-proxy integrations, activate CORS and add the allowed domains.

No Access-Control-Allow-Headers header

If you didn't configure headers in the CORS settings, then you receive the following error message:

"No 'Access-Control-Allow-Headers' header present"

For proxy integrations, add the "Access-Control-Allow-Headers": "Content-Type,X-Amz-Date,Authorization,X-Api-Key" header to your backend integration.

For non-proxy integrations, add the required headers in the API Gateway CORS settings.

No Access-Control-Allow-Methods header

If you didn't configure your HTTP methods in the CORS settings, then you receive the following error message:

"No 'Access-Control-Allow-Methods' header present"

For proxy integrations, add the "Access-Control-Allow-Methods": "OPTIONS, POST, GET" header to your backend integration.

Note: Replace OPTIONS, POST, GET with the methods that you require for your proxy integration.

For non-proxy integrations, configure the allowed methods in the API Gateway CORS settings.

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

For private REST APIs, check if you activated private DNS on the associated interface virtual private cloud (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 Amazon route 53 alias invoke URL format:

https://rest_api_id-vpce_id.execute-api.region.amazonaws.com/stage

Note: Replace rest_api_id, vpce_id, region, and stage with your API values.

If you didn't activate private DNS, then you can't use endpoint-specific public DNS names to access your private API from within your 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 you turned off authorization in the OPTIONS method of your API.

Related information

Test CORS for an API Gateway API

Activate CORS on a resource using the API Gateway import API