How do I troubleshoot HTTP 403 Forbidden errors from API Gateway?

An HTTP 403 response code means that a client is forbidden from accessing a valid URL. The server understands the request, but it can't fulfill the request due to client-side issues.

API Gateway APIs can return 403 Forbidden responses for a variety of reasons:

Follow these troubleshooting steps to help determine the cause of the error.

Consider the source of the error

If the 403 error was reported from other resources, there might be another cause for the error. For example:

• If the error was reported in a web browser, it can be caused by an incorrect proxy setting. The proxy server returns a 403 error if HTTP access isn't allowed.
• If there's another AWS service in front of the API (for example, Amazon CloudFront), that service can reject the request with a 403 error in the response.

Enable API access logging to investigate.

Confirm that the requested resource exists in the API definition

Check for the requested resource in the API using either the API Gateway console or the AWS Command Line Interface (AWS CLI).

Note: The API must be deployed with the latest API definition.

Use curl to get request and response details

If the error can be reproduced, you can use curl -v to get more details between the client and the API. For example:

curl -X GET -v https://apiId.execute-api.region.amazonaws.com/stageName/resourceName

For more information about curl, see the curl project website.

Check the header

If the error is about an API key, verify that the "x-api-key" header was sent in the request.

Check the DNS setting on a VPC endpoint

If the API is invoked from an Amazon VPC that has an interface VPC endpoint, verify that the DNS setting of the interface endpoint is set correctly based on the API type.

• To invoke a Regional API from inside an Amazon VPC, private DNS must be disabled on the interface endpoint. Then, the endpoint's hostname can be resolved by a public DNS. For more information, see Why do I get an HTTP 403 Forbidden error when connecting to my API Gateway APIs from a VPC?
• To invoke a private API from inside an Amazon VPC using the API's private DNS name, private DNS must be enabled on the interface endpoint. Then, the interface endpoint's hostname can be resolved to the Amazon VPC's local subnet resources. For more information, see How to invoke a private API.
  Note: You don't need to enable private DNS if you're invoking the private API using its public DNS name or an Amazon Route 53 alias.

Check the resource policy

Verify the following:

• If the API is invoked from an Amazon VPC with an interface VPC endpoint, the API's resource policy must grant the Amazon VPC or the interface endpoint access to the API.
• The resource policy's resource specifications and formatting are correct. (There's no validation of the resource specification when saving a resource policy.) For examples, see API Gateway resource policy examples.

Analyze API access logs

Enable and analyze the API's access logs to determine whether requests are reaching the API.

Analyze HTTP request and response messages

If you can, reproduce the error in a web browser and use the browser's network tools to capture the HTTP request and response messages for analysis. For offline analysis, save these messages in an HTTP Archive (HAR) file.

Tip: For instructions on creating a HAR file, see How do I create a HAR file from my browser for an AWS Support case?

Analyze the requests and responses between the client and the API to find out where the error occurred.