API Gateway Anti-Patterns: Failure Signals and Safer Designs

Diagnose gateway responsibility creep, unsafe authorization, shared configuration failures and misleading health checks before adding more infrastructure.

Start with a failing route, not a gateway replacement

An API gateway becomes a problem when its responsibilities, failure boundaries or ownership are unclear. That does not mean every slow request needs a different gateway, or that a shared entry point is inherently a single point of failure.

Start with one affected route. Identify the caller, gateway configuration revision, selected upstream, downstream result and time spent at each boundary. A gateway waiting on an overloaded service needs a different fix from a gateway spending its own CPU transforming responses.

This article is a troubleshooting guide for an existing deployment. For choosing a gateway, backend-for-frontend or aggregation pattern, see API gateway patterns for microservices.

| Signal | Evidence to collect before changing the design | |---|---| | Unrelated routes slow down together | Gateway resource saturation, connection queues, shared plugins and common dependencies. | | Only one route is slow | Upstream latency, payload size, fan-out and route-specific policies. | | Healthy replicas return incorrect responses | Active configuration on each replica, upstream version and a real contract check. | | Tenant-specific data appears in another response | Authorization decisions, cache keys and trust in forwarded identity headers. | | Every product change needs a platform release | Which gateway rules contain domain decisions rather than transport policy. |

Anti-pattern: every responsibility becomes a gateway rule

Routing, authentication, rate limits and protocol handling commonly belong at the edge. Lightweight response composition can belong there too. A blanket rule that gateways must never aggregate responses is not useful.

The boundary becomes problematic when a gateway must decide pricing, reserve inventory, coordinate compensation or hold a long-running business transaction open. Those responsibilities bring domain state, different release needs and failure behavior into infrastructure shared by unrelated APIs.

A backend-for-frontend can own client-specific composition behind the gateway when it needs independent scaling, testing or deployment. It should still call domain services for authoritative decisions. Microsoft's gateway aggregation guidance distinguishes lightweight composition from complex domain logic and orchestration.

Use these questions in a route review:

• Can this rule be tested without reproducing a business workflow?
• Does a change affect one client experience or the shared entry path?
• Does the operation require durable state or compensation?
• Who owns the result when one dependency fails?
• Can the component scale and deploy independently when its workload diverges?

For a dashboard, returning a clearly marked unavailable recommendation panel may be acceptable. Returning a partial payment authorization as if it were complete is not. Define partial-result semantics in the API contract, not in an emergency gateway fallback.

Anti-pattern: authentication at the edge replaces authorization

A valid token tells you something about the caller. It does not establish that the caller may read a particular invoice, change another user's role or act in the tenant named by a request parameter.

The service that owns the resource needs an enforceable authorization decision using authenticated identity and current resource context. A shared policy engine can help, but the gateway should not infer ownership from a URL or trust a client-supplied tenant header. OWASP's object-level authorization guidance explains this distinction.

Strip or reject untrusted identity headers at the boundary, and authenticate the channel used to forward trusted context. Test direct upstream access as well as the gateway path. Otherwise, a bypass route can turn an apparently protected service into an exposed one.

Treat response caching as part of this review. A cache keyed only by the path can cross authorization boundaries if the response also depends on identity or tenant. Disable shared caching for that route until the team can establish correct partitioning, authorization and invalidation behavior. A shorter cache lifetime does not make a cross-tenant response safe.

Anti-pattern: every layer retries an uncertain operation

A timeout does not tell the caller whether the upstream committed a write. Adding gateway retries can duplicate work if the application has no durable deduplication contract.

Document which layer owns retries, which failures qualify and how the overall request deadline limits further attempts. For a write, establish a verified idempotency contract before allowing gateway retries; otherwise leave automatic retries disabled. HTTP semantics in RFC 9110 prohibit a proxy from automatically retrying non-idempotent requests. Reusing a request ID in logs is not a deduplication mechanism: the service must recognize repeated intent and return or reconcile the original result.

For a read-only aggregation, bound both fan-out and waiting time. If an optional dependency exhausts its budget, return the documented partial response or fail explicitly. Do not keep retrying until every caller, connection pool and downstream queue is occupied.

The recovery boundary matters too. Cancelling a gateway request does not prove the downstream transaction stopped. Check operation status or reconcile the result before asking the user to submit again.

Worked example: replicas cannot undo a bad shared configuration

Consider a hypothetical orders API with gateway replicas across two availability zones. A route update points all replicas to a new upstream that returns an incompatible response. The gateway processes remain healthy and the upstream returns HTTP 200, but clients cannot parse the result.

Adding replicas would not fix this incident. The shared configuration rollout exposed every replica to the same mistake.

| Boundary | Safer control | |---|---| | Before propagation | Validate route syntax, policy compatibility and response contracts against the intended upstream. | | First exposure | Apply the change to an isolated subset of traffic with a known configuration identity. | | Continue or stop | Compare real route results and client-visible failures, not just process health. | | Recovery | Stop the propagator and restore the last known-good compatible configuration. | | Verification | Check the configuration actually active on each replica and exercise the affected route. |

A control-plane acknowledgment is useful evidence, but not a successful customer request. Envoy's xDS protocol documentation states that an ACK means individual resources were considered valid; it does not guarantee successful application.

Keep the previous configuration available and make its restoration an exercised procedure. Check whether other upstream or certificate changes made that version unsafe to restore. Preserve authentication and authorization during recovery. Disabling them to make a health check pass changes the incident into a security exposure.

If the faulty route already triggered writes, configuration rollback only stops or redirects future traffic. The service owner must separately identify affected operations and reconcile data or external side effects.

Anti-pattern: gateway telemetry hides the actual boundary

Record enough context to distinguish gateway rejection, queueing, connection failure, upstream response and client cancellation. Use route templates rather than raw URLs as metric dimensions so customer IDs do not create unbounded labels.

Propagate trace context deliberately. An incoming trace ID is correlation data, not identity or authorization evidence. Validate untrusted headers and apply a policy at trust boundaries. The W3C Trace Context specification also prohibits putting personally identifiable or other sensitive information into its tracing headers.

Do not log tokens, session cookies or complete payloads merely to connect requests. A diagnostic record can usually reference a restricted operation ID while keeping customer data in its authorized system.

When gateway and upstream dashboards disagree, inspect one sampled request end to end before changing global timeouts. A higher timeout can conceal queue growth while increasing the number of requests waiting for the same bottleneck.

Run a bounded gateway review

Choose one important route and leave the review with:

1. A named owner for transport policy, composition and domain authorization.
2. A trace showing where time and failure originate.
3. A test for denied access, dependency failure and an uncertain write outcome.
4. A versioned configuration change with limited initial exposure.
5. A recovery procedure that preserves security and separates traffic recovery from data repair.

If the route crosses too many responsibilities to make those decisions clearly, use a backend systems and API review to map the boundary before replacing infrastructure. Bring the route contract, sanitized failure trace and current configuration rollout procedure. Those are more useful starting points than a vendor shortlist.

Primary references were checked in September 2026. The incident above is an illustrative design exercise, not an Ampity client result.