How do I troubleshoot HTTP 403 errors from API Gateway?

Last updated: 2022-11-21

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 fulfill 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 an API Gateway 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 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.

For more information, see How do I troubleshoot 403 "Missing Authentication Token" errors from an API Gateway REST API endpoint?

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 Disabling 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?

Invoking a custom domain name without a base path mapping

"x-amzn-errortype" = "ForbiddenException"

"Forbidden"

The caller invokes a custom domain without a base path being mapped to an API.

 

For more information, see Setting up custom domain names for REST APIs.

Invoking an API with custom domain enabled when the domain URL includes the stage

"x-amzn-errortype" = "MissingAuthenticationTokenException"

"Missing Authentication Token"

An API mapping specifies an API, a stage, and optionally a path to use for the mapping. Therefore, when an API's stage is mapped to a custom domain, you no longer need to include the stage in the URL.

For more information, see Working with API mappings for REST APIs.

Stage in request URL is not valid
"x-amzn-errortype" = "ForbiddenException"
"Forbidden"

The caller's request URL includes a stage that doesn't exist. Verify that the stage exists and the spelling of the request URL.

For more information, see Invoking a REST API in Amazon API Gateway.

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 done so 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 similar to the following:

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 Amazon 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:

  • To invoke a Regional API from inside an Amazon VPC, private DNS names must be deactivated on the interface endpoint. Then, the endpoint's hostname can be resolved by a public DNS. For more information, see Creating a private API in Amazon API Gateway.
  • To invoke a private API from inside an Amazon VPC using the API's private DNS name, private DNS names must be activated 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 set up a private DNS if you're invoking the private API using either of the following:
    The private API's public DNS name.
    -or-
    An Amazon Route 53 alias.

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.