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

Last updated: 2021-05-19

When I call my Amazon API Gateway API, I get a 403 Forbidden error. How do I troubleshoot the error?

Short description

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 because of client-side issues.

API Gateway APIs can return 403 Forbidden responses for any of the following reasons:

Issue Response header Error message Details
Access denied "x-amzn-ErrorType" = "AccessDeniedException" "User is not authorized to access this resource with an explicit deny" The caller isn't authorized to access an API that's using a Lambda authorizer.
Access denied "x-amzn-ErrorType" = "AccessDeniedException" "User: <user-arn> is not authorized to perform: execute-api:Invoke on resource: <api-resource-arn> with an explicit deny"

The caller isn't authorized to access an API that's using AWS Identity and Access Management (IAM) authorization. Or, the API has an attached resource policy that explicitly denies access to the caller.

For more information, see IAM authentication and resource policy.

Access denied "x-amzn-ErrorType" = "AccessDeniedException" "User: anonymous is not authorized to perform: execute-api:Invoke on resource: <api-resource-arn>"

The caller isn't authorized to access an API that's using IAM authorization. Or, the API has an attached resource policy that doesn't explicitly allow the caller to invoke the API.

For more information, see IAM authentication and resource policy.

Access denied "x-amzn-ErrorType" = "AccessDeniedException" "The security token included in the request is invalid." The caller used invalid IAM keys to access an API that's using IAM authorization.
Missing authentication token "x-amzn-ErrorType" = "MissingAuthenticationTokenException" "Missing Authentication Token" An authentication token wasn't found in the request.
Authentication token expired "x-amzn-ErrorType" = "InvalidSignatureException" "Signature expired" The authentication token in the request has expired.
API key isn't valid "x-amzn-ErrorType" = "ForbiddenException" "Invalid API Key identifier specified" The caller used an invalid API key for a method that requires an API key.
Signature isn't valid "x-amzn-ErrorType" = "InvalidSignatureException" "The request signature we calculated does not match the signature you provided. Check your AWS Secret Access Key and signing method." The signature in the request doesn't match that on the server when accessing an API that's using IAM authorization.
AWS WAF filtered "x-amzn-ErrorType" = "ForbiddenException" "Forbidden" The request is blocked by web application firewall (WAF) filtering when AWS WAF is activated in the API.
Resource path doesn't exist "x-amzn-ErrorType" = "MissingAuthenticationTokenException" "Missing Authentication Token" A request with no "Authorization" header is sent to an API resource path that doesn't exist.
Resource path doesn't exist "x-amzn-ErrorType" = "IncompleteSignatureException" "Authorization header requires 'Credential' parameter. Authorization header requires 'Signature' parameter. Authorization header requires 'SignedHeaders' parameter. Authorization header requires existence of either a 'X-Amz-Date' or a 'Date' header. Authorization=allow" A request with an "Authorization" header is sent to an API resource path that doesn't exist.
Invoking a private API using public DNS names incorrectly "x-amzn-ErrorType" = "ForbiddenException" "Forbidden"

When invoking a private API from within an Amazon Virtual Private Cloud (Amazon VPC) using public DNS names, the "Host" or "x-apigw-api-id" header is missing in the request.

For more information, see Invoking your private API using endpoint-specific public DNS hostnames.

Invoking a REST API that has a custom domain name using the default execute-api endpoint.

"x-amzn-ErrorType" = "ForbiddenException" "Forbidden"

The caller uses the default execute-api endpoint to invoke a REST API after disabling the default endpoint.

For more information, see Disabling the default endpoint for a REST API.

Resolution

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, then that error might 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), then that service can reject the request with a 403 error in the response.

Set up 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, use curl -v to get more details between the client and the API.

curl -v command example

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

For more information, 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.

Keep in mind the following:

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

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

Analyze HTTP request and response messages

If you can do so, reproduce the error in a web browser, and then 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.

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

Then, analyze the requests and responses between the client and the API to determine where the error occurred.