Troubleshoot API gateway header rewrites on some routes

Sure — “header rewrites on some routes” usually means one of a few things: the gateway is applying the rewrite inconsistently, a route matcher is more specific than expected, another policy is overriding it, or the backend/proxy chain is changing headers after the gateway.

Here’s a practical troubleshooting checklist.

1) Confirm the route is actually matching

A rewrite won’t apply if the request is hitting a different route than you think.

Check:

• Path prefixes vs exact matches
• Method-specific routes
• Host-based routing
• Priority/order of routes
• Trailing slashes and URL normalization
• Regex path rules

Common issue:

• /api/v1/users matches one route
• /api/v1/users/ matches another
• GET has the rewrite, POST does not

2) Verify the rewrite rule scope

Some gateways apply header transforms:

• per route
• per service/upstream
• per consumer/API key
• per stage/environment
• only on request headers, not response headers

Make sure the rewrite is defined in the same place as the matched route.

3) Check for conflicting plugins/policies

A later policy may overwrite or remove the header.

Look for:

• Multiple header transformation rules
• Global policies
• Upstream service defaults
• WAF/security plugins
• Auth plugins adding Authorization, X-User-*, etc.
• CORS or caching policies changing response headers

Rule of thumb:

• If one policy sets X-Env: prod and another sets X-Env: staging, the later one may win.

4) Inspect the actual request at the gateway boundary

Use gateway logs or tracing to see what headers arrive and what gets forwarded.

Compare:

• Client sent headers
• Gateway received headers
• Gateway forwarded headers
• Backend received headers

If possible, log:

• original request headers
• rewritten headers
• matched route ID/name
• applied plugins/policies

5) Determine whether the header is hop-by-hop or restricted

Some headers are not safely rewriteable or may be stripped:

• Host
• Content-Length
• Connection
• Transfer-Encoding
• Upgrade
• Expect
• Authorization in some security configurations

If rewriting Host, check whether the gateway also needs an upstream host override or SNI config.

6) Check whether the backend or another proxy changes it again

Your gateway may be correct, but:

• load balancer
• ingress controller
• sidecar proxy
• service mesh
• backend app framework

…may override or ignore headers.

To isolate:

• send traffic directly to backend if possible
• compare with and without upstream proxies
• add a test endpoint that echoes headers

7) Validate header casing and duplication behavior

HTTP headers are case-insensitive, but some tools display them inconsistently.

Be aware of:

• duplicate headers with same name
• gateway merging behavior
• backend frameworks that only read first/last occurrence
• underscore vs hyphen differences (X_Foo vs X-Foo)

8) Test with a minimal route

Create one simple test route:

• one path
• one header rewrite
• one backend echo service

If this works, the problem is likely route specificity or policy conflict in the real config.

Example test:

• Request: /test
• Rewrite: X-Debug: true
• Backend echoes received headers

9) Check config ordering / precedence

Many gateways evaluate transforms in a defined order.

Possible precedence:

1. global settings
2. service-level settings
3. route-level settings
4. plugin order
5. per-request overrides

If only some routes fail, the route-level setting may be getting overridden by a broader config.

10) Watch for caching

If you have caching anywhere:

• stale config may be active
• old route definitions may still be loaded
• gateway worker processes may need reload/restart

Try:

• config reload
• clearing admin cache
• restarting gateway pods
• checking deployment rollouts

---

Fast isolation workflow

1. Identify one failing route and one working route.
2. Compare their exact match conditions.
3. Dump effective config for both.
4. Enable trace/logging for header transforms.
5. Send the same request to both.
6. Inspect what reaches the backend.

---

If you want, I can help you debug it more concretely

Send me:

• which API gateway you’re using (Kong, Apigee, NGINX, AWS API Gateway, Azure APIM, Traefik, Istio, etc.)
• an example route config
• the header rewrite rule
• one request that works and one that doesn’t
• expected vs actual headers

And I can help pinpoint the likely cause.