How do I troubleshoot HTTP 403 errors from API Gateway?

Last updated: 2021-12-16

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

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

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

Issue Response header Error message Root cause
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 IAM keys that aren't valid 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 API key that's not valid 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"

Invoking a private API from within an Amazon Virtual Private Cloud (Amazon VPC) using public DNS names incorrectly. For example: 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 deactivating the default endpoint.

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

Invoking an API Gateway custom domain name that requires mutual Transport Layer Security (TLS) using a client certificate that's not valid. "x-amzn-errortype" = "ForbiddenException" "Forbidden"

The client certificate presented in the API request isn't issued by the custom domain name's truststore, or it isn't valid.

For more information, see How do I troubleshoot HTTP 403 Forbidden errors from an API Gateway custom domain name that requires mutual TLS?

Resolution

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, then that service can reject the request with a 403 error in the response. For example: Amazon CloudFront.

Identify what's causing the error

If you haven't already, set up Amazon CloudWatch access logging for your API. Then, view your API's execution logs in CloudWatch to determine if requests are reaching the API.

Note: HTTP APIs don't support execution logging. To troubleshoot 403 errors returned by a custom domain name that requires mutual TLS and invokes an HTTP API, you must do the following:

1.    Create a new API mapping for your custom domain name that invokes a REST API for testing only.

2.    Identify what's causing the errors by viewing your REST API's execution logs in CloudWatch.

3.    After the error is identified and resolved, reroute the API mapping for your custom domain name back to your HTTP API.

Confirm that the requested resource exists in the API definition

Note: If you receive errors when running AWS Command Line Interface (AWS CLI) commands, make sure that you're using the most recent AWS CLI version.

Verify the following using either the API Gateway console or the AWS CLI:

  • The API is deployed with the latest API definition.
  • The requested resource exists in the API definition.

Use curl to get request and response details

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

curl -v command example

curl -X HTTP_VERB -v https://{api_id}.execute-api.{region}.amazonaws.com/{stage_name}/{resource_name}

Note: For more information, see the curl project website.

Verify that the request header is correct

If the error is the result of an API key that's not valid, then verify that the "x-api-key" header was sent in the request.

Verify that the DNS setting on any interface VPC endpoints is set correctly

Note: Confirm the following for APIs invoked from an Amazon VPC that has an interface VPC endpoint only.

Verify that the DNS setting of the interface endpoint is set correctly based on the type of API that you're using.

Keep in mind the following:

Review the API's resource policy

Review your API's resource policy to verify the following:

Review HTTP request and response messages

Reproduce the error in a web browser, if possible. Then, use the browser's network tools to capture the HTTP request and response messages and analyze them to determine where the error occurred.

Note: For offline analysis, save the messages in an HTTP Archive (HAR) file.