AWS API Gateway Error: Custom Domain & Base Path Mapping Failures
.jpeg)
How API Gateway APIs work correctly on execute-api URLs but fail on custom domains due to stage mappings, base path configuration, DNS targeting mistakes, or domain-level routing mismatches
Problem
You deploy an API in Amazon API Gateway and verify it works perfectly using the default invoke URL:
https://abc123.execute-api.us-east-1.amazonaws.com/prod/users
Then you attach a custom domain, such as:
https://api.example.com
Suddenly:
- Requests return
403 Forbidden - Requests return
Missing Authentication Token - Requests return
404 Not Found - Or nothing reaches the backend at all
The API works.
The domain resolves.
But traffic fails only when using the custom domain.
Clarifying the Issue
Custom domains in API Gateway do not automatically mirror your API’s routing structure.
Instead, they rely on Base Path Mappings, which explicitly define:
- Which API receives traffic
- Which stage is invoked
- Which URL paths are preserved or removed
Additionally:
- Custom domains are backed by managed CloudFront or regional endpoints
- DNS must target the API Gateway domain endpoint, not the API itself
- Changes take time to propagate
In short:
A custom domain is just a router.
If it doesn’t know where to send traffic—or isn’t fully initialized—nothing works.
Why It Matters
Custom domain failures are especially deceptive because:
- DNS resolves correctly
- TLS certificates appear valid
- The same API works on
execute-api - Errors look identical to auth or routing failures
Teams often misdiagnose this as:
- IAM issues
- Authorizer failures
- CORS problems
- Backend outages
In reality, the request never reaches the API stage you expect.
Understanding domain-level routing and initialization eliminates this entire class of false debugging.
Key Terms
- Custom Domain – A user-defined hostname mapped to API Gateway
- Base Path Mapping – Rules mapping domain paths to APIs and stages
- Stage – A deployed runtime snapshot of an API
- Invoke URL – The default
execute-apiendpoint - Domain Name Target – The API Gateway–provided DNS target for the custom domain
- Propagation Delay – Time required for the domain to become active globally
Steps at a Glance
- Verify the API works via
execute-api - Confirm the custom domain configuration and DNS target
- Allow for domain initialization and propagation
- Inspect Base Path Mappings
- Understand stage removal vs path preservation
- Check for multi-API domain conflicts
- Retest using the correct custom-domain URL
Detailed Steps
Step 1: Prove the API Works Without the Custom Domain
Invoke the API using its default URL:
https://abc123.execute-api.us-east-1.amazonaws.com/prod/users
If this fails, stop.
This is not a custom domain problem.
Custom domains only route traffic — they do not fix broken APIs.
Step 2: Confirm the Custom Domain and DNS Target (Critical)
In API Gateway, each custom domain exposes a Domain Name Configuration target, such as:
d-xyz123.execute-api.us-east-1.amazonaws.com
Your DNS record must point to this target, not to the API invoke URL.
❌ Incorrect (common mistake):
api.example.com → abc123.execute-api.us-east-1.amazonaws.com
✅ Correct:
api.example.com → d-xyz123.execute-api.us-east-1.amazonaws.com
Pointing DNS at the invoke URL causes:
- TLS certificate mismatches
- Connection failures
- Hard-to-diagnose SSL errors
Step 3: Allow for Domain Initialization (The 403 Trap)
When you create or update a custom domain:
- API Gateway provisions infrastructure behind the scenes
- This process can take 15–40 minutes
During this window:
- DNS may resolve
- Requests may return 403 Forbidden
- Or connections may intermittently fail
If you see a 403 immediately after creating or updating a domain, wait before debugging.
Breaking a correct configuration during propagation is a very common mistake.
Step 4: Inspect Base Path Mappings (Primary Failure Point)
Base Path Mappings define how URLs are translated.
Examples:
| Base Path | API | Stage | Resulting URL |
|---|---|---|---|
| (empty) | my-api | prod | /users |
v1 | my-api | prod | /v1/users |
Common mistakes:
- No base path mapping exists
- Mapping points to the wrong stage
- Mapping points to the wrong API
- Assuming the stage name is automatically preserved
Step 5: Understand Stage Removal vs Path Preservation
If your base path mapping is empty:
https://api.example.com/users ✅
https://api.example.com/prod/users ❌
If your base path is prod:
https://api.example.com/prod/users ✅
https://api.example.com/users ❌
Custom domains often remove the stage from the URL entirely.
Reusing the execute-api URL structure against a custom domain will fail.
Step 6: Watch for Multi-API Domain Conflicts
A single custom domain can route to multiple APIs.
Examples:
/users→ User API/orders→ Orders API
Common pitfalls:
- Overlapping base paths
- Root (
/) mapping shadowing others - New APIs added without updating mappings
Ambiguous routing causes silent failures.
Step 7: Retest Using the Correct Custom-Domain URL
Once confirmed:
- DNS targets the domain configuration endpoint
- The domain has fully initialized
- Base path mappings are correct
Retest using:
- The custom domain
- The correct base path
- No stage name unless explicitly mapped
When routing is correct, most errors disappear instantly.
Pro Tips
- If
execute-apiworks, the API is fine. - DNS must point to the API Gateway domain target, not the invoke URL.
- New domains can return 403s for up to 40 minutes — wait first.
- Empty base paths remove the stage from the URL.
- Custom domains only route; they do not deploy or authorize.
- Ambiguous mappings break everything quietly.
Conclusion
Custom domain failures are almost never caused by:
- IAM
- Authorizers
- CORS
- Backend code
They are caused by routing and infrastructure mismatches at the domain layer.
Once you understand:
- Domain initialization timing
- Correct DNS targeting
- Base Path Mapping behavior
Debugging becomes mechanical instead of mystical.
If the API works on execute-api but fails on a custom domain, stop looking elsewhere.
Check the domain.
Check the mapping.
Aaron Rose is a software engineer and technology writer at tech-reader.blog and the author of Think Like a Genius.
Comments
Post a Comment