How can I resolve DNS resolution or SSL certificate mismatch errors for my API Gateway custom domain name?

2 minute read

I configured a custom domain name for my Amazon API Gateway API. I am unable to connect to the domain name and receive DNS resolution or SSL certificate mismatch errors. How can I resolve this?

Short description

There are two types of custom domain names that you can create for API Gateway APIs: Regional or (for REST APIs only) edge-optimized.


Before creating a custom domain name for your API, you must do one of the following:

Request an SSL/TLS certificate from AWS Certificate Manager (ACM).
Import an SSL/TLS certificate into ACM.

For more information, see Getting certificates ready in AWS Certificate Manager.

After you have your SSL/TLS certificate, you can follow the instructions to set up a custom domain name for my API Gateway API.

To connect to a custom domain name for API Gateway APIs, you must configure Amazon Route 53 to route traffic to an API Gateway endpoint.

If the DNS records for the custom domain name aren't mapped to the correct API Gateway domain name, then the SSL connection fails. This is because the default *.execute-api.<region> certificate is returned instead of the SSL/TLS certificate.

To confirm that the DNS mapping is correct, run the following command from the client:

$ nslookup <customdomainname>

The output should be the API Gateway domain name. Make sure that the domain name matches the API Gateway domain name. If a Route 53 alias record is used for DNS mapping, then the output is the IP address. Make sure that the IP address matches the API Gateway domain name IP address.


  • When configuring Route 53, you must create either a public hosted zone or a private hosted zone. For internet-facing applications with resources that you want to make available to users, choose a public hosted zone. For more information, see Working with hosted zones.
  • Route 53 uses records to determine where traffic is routed for your domain. Alias records provide easier DNS queries to AWS resources, while CNAME (non-alias) records can redirect DNS queries outside of AWS resources. For more information, see Choosing between alias and non-alias records.

Related information

Migrating a custom domain name to a different API endpoint

AWS OFFICIALUpdated 2 years ago