Get Hands-on with Amazon EKS - Workshop Event Series

Whether you're taking your first steps with Kubernetes or you're an experienced practitioner looking to sharpen your skills, our Amazon EKS workshop series delivers practical, real-world experience that moves you forward. Learn directly from AWS solutions architects and EKS specialists through hands-on sessions designed to build your confidence with Kubernetes. Register now and start building with Amazon EKS!

How do I troubleshoot HTTP 403 errors from API Gateway?

9 minute read

When I call my Amazon API Gateway API, I get a 403 error.

Short description

You get an "HTTP 403" status code error when a client can't access a valid URL. The server understands the request, but client-side issues don't allow the server to fulfill the request.

API Gateway APIs might return "HTTP 403" errors for 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 in an identity-based policy"	The API Gateway Lambda authorizer that the API uses doesn't authorize the caller.
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 AWS Identity and Access Management (IAM) authorization that the API uses doesn't authorize the caller. Or, the resource policy that's attached to the API 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 IAM authorization that the API uses doesn't authorize the caller. Or, the resource policy that's attached to the API 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 uses IAM authorization.
API key isn't valid	"x-amzn-errortype" = "ForbiddenException"	"Forbidden"	The caller used an incorrect API key against a method that requires an API key. Or, you didn't associate the API key to a usage plan that connects to the stage. Or, you turned off the API key, or the key doesn't exist.
AWS WAF filtered	"x-amzn-errortype" = "ForbiddenException"	"Forbidden"	Web application firewall filtering blocks the request when you activate AWS WAF in the API.
Incorrectly uses public DNS names to invoke a private API	"x-amzn-errortype" = "ForbiddenException"	"Forbidden"	You incorrectly used public DNS names to invoke a private API from within an Amazon Virtual Private Cloud (Amazon VPC). For example, the Host or x-apigw-api-id header is missing in the request. For more information, see Invoke a private API using endpoint-specific public DNS hostnames.
Invokes a custom domain name without a base path mapping	"x-amzn-errortype" = "ForbiddenException"	"Forbidden"	The caller invokes a custom domain and doesn't map a base path to an API. For more information, see Custom domain name for public REST APIs in API Gateway.
Invokes a private custom domain name	"x-amzn-errortype" = "ForbiddenException"	"Forbidden"	You didn't associate the private custom domain name with the VPC endpoint.
Stage in request URL isn't valid	"x-amzn-errortype" = "ForbiddenException"	"Forbidden"	The caller's request URL includes a stage that doesn't exist. For more information, see Invoke REST APIs in API Gateway.
Uses a client certificate that's not valid to invoke an API Gateway custom domain name that requires mutual TLS	"x-amzn-errortype" = "ForbiddenException"	"Forbidden"	The custom domain name's truststore doesn't issue the client certificate that's in the API request, or the certificate 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?
Uses the default execute-api endpoint to invoke a REST API that has a custom domain name	"x-amzn-errortype" = "ForbiddenException"	"Forbidden"	The caller uses the default execute-api endpoint to invoke a REST API after you deactivate the default endpoint. For more information, see Disable the default endpoint for REST APIs.
Uses routing rules with custom domain name	"x-amzn-errortype" = "ForbiddenException"	"Forbidden"	You didn't configure a matching routing rule with the custom domain name. For more information, see Troubleshooting issues with routing rules.
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"	You sent a request with an Authorization header to an API resource path that doesn't exist.
Authentication token expired	"x-amzn-errortype" = "InvalidSignatureException"	"Signature expired"	The request's authentication token expired.
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 the signature on the server when the caller accesses an API that uses IAM authorization.
Invokes an API with custom domain turned on when the domain URL includes the stage	"x-amzn-errortype" = "MissingAuthenticationTokenException"	"Missing Authentication Token"	An API mapping specifies an API, a stage, and an optional path to use for the mapping. When you map an API's stage to a custom domain, you don't need to include the stage in the URL. For more information, see Use API mappings to connect API stages to a custom domain name for REST APIs.
Missing authentication token	"x-amzn-errortype" = "MissingAuthenticationTokenException"	"Missing Authentication Token"	The request doesn't have an authentication token.
Missing authentication token	"x-amzn-errortype" = "MissingAuthenticationTokenException"	"Missing Authentication Token"	You sent a request to an API method that doesn't exist in the API.
Missing authentication token	"x-amzn-errortype" = "MissingAuthenticationTokenException"	"Missing Authentication Token"	You sent a request to an API resource that doesn't exist in the API.
Resource path doesn't exist	"x-amzn-errortype" = "MissingAuthenticationTokenException"	"Missing Authentication Token"	You sent a request with no Authorization header to an API resource path that doesn't exist. For more information, see How do I troubleshoot API Gateway REST API endpoint 403 "Missing Authentication Token" errors?

Resolution

Confirm that the requested resource exists in the API definition

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Use either the API Gateway console or the AWS CLI to verify the following configurations:

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

Identify the cause of the error

To identify the cause of the error, set up Amazon CloudWatch access logging for your API. Then, view your API's log events in CloudWatch to determine if the requests reach the API Gateway API. If the requests reach the API Gateway API and there are error messages in your logs, then you can continue to troubleshoot API Gateway. If the requests reach other resources, then other proxies or services might be the cause of the error.

Note: HTTP APIs don't support execution logging.

If you can reproduce the error, then use the curl -v command to get more communication details between the client and the API:

curl -X HTTP\_VERB -v https://api-id.execute-api.region.amazonaws.com/stage

Note: Replace the example URL with the API's invoke URL.

Verify your REST API and reroute the API mapping

If you use a custom domain name that requires mutual TLS and invokes an HTTP API, then you might receive 403 errors.

Create a new API mapping to test the REST API invocation for your custom domain name. To identify the cause of the errors, view your REST API's log events in CloudWatch. After you identify and resolve the error, reroute the API mapping to your HTTP API.

Verify that the request header is correct

If the error is the result of an API key that isn't valid, then verify that you sent the x-api-key header in the request. If you didn't include the header or it isn't correct, then update the request header.

Verify that you correctly configured the DNS setting on interface Amazon VPC endpoints

Note: The following tasks apply for APIs that you invoke from an Amazon VPC that has only an interface VPC endpoint.

Verify that you correctly configured the interface endpoint's DNS setting based on the type of API that you use.

To invoke an AWS Regional API from inside an Amazon VPC, deactivate private DNS names on the interface endpoint. A public DNS can then resolve the endpoint's hostname. For more information, see Create a private API.

To use the API's private DNS name to invoke a private API from inside an Amazon VPC, activate the private DNS names on the endpoint. The Amazon VPC local subnet resources can then resolve the interface endpoint's hostname.

Note: If you activate private DNS and use the default URI, then you don't need to set up 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 configurations:

For APIs that you invoke from a VPC with an interface VPC endpoint, the API's resource policy must grant access to the VPC or interface VPC endpoint.
The resource policy has the correct resource specifications and formatting.
Note: When you save a resource policy, API Gateway doesn't validate the ARN specifications. For examples, see API Gateway resource policy examples.
API Gateway allows the caller to invoke the API endpoint by the authentication type that you defined for the API. API Gateway evaluates the resource policy and the authorization type to allow or reject requests.

Review HTTP request and response messages

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

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