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

Last updated: 2020-03-02

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 won't fulfill the request due to client-side issues.

API Gateway APIs can return 403 Forbidden responses for a variety of 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.
Invalid API key "x-amzn-ErrorType" = "ForbiddenException" "Invalid API Key identifier specified" The caller used an invalid API key for a method that requires an API key.
Invalid signature "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 enabled 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.
Incorrect private DNS setting in interface VPC endpoint "x-amzn-ErrorType" = "MissingAuthenticationTokenException" "Missing Authentication Token" When accessing a private API from within an Amazon Virtual Private Cloud (Amazon VPC) using private DNS names, private DNS isn't enabled on the VPC endpoint. Or, when accessing a private API using a VPC endpoint, the "Host" header is missing.

For more information, see How to Invoke a Private 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, 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).

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

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 in an Amazon VPC with an interface VPC endpoint, verify that the DNS setting of the interface endpoint is set correctly based on the API type.

Check the resource policy

Verify the following:

  • If the API is in an Amazon VPC with an interface VPC endpoint, the API's resource policy grants the Amazon VPC and 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.