HTTP 502 bad gateway: What Testers Need to Know

TL;DR

HTTP 502 Bad Gateway means an intermediary acting as a gateway or proxy could not use the response it received from an upstream server. Test the gateway-upstream boundary with controlled protocol and connection failures, assert safe external behavior, inspect whether work reached the upstream, and prove recovery without unsafe retries.

Key Takeaways

• 502 means a gateway or proxy received an invalid response from an upstream server while trying to fulfill the request.
• Identify the gateway hop and upstream hop before assigning the defect to the frontend or application.
• Reproduce connection closure, protocol mismatch, invalid headers, TLS failure, and partial responses with controlled upstream doubles.
• Distinguish 502 from an upstream timeout, local application exception, no-ready-capacity state, and client error.
• Verify retry safety and ambiguous write outcomes because the upstream may have processed work before the gateway failed.
• Correlate edge, gateway, and upstream evidence while keeping public error bodies free of topology and secrets.

The http status 502 bad gateway response means that a server acting as a gateway or proxy received an invalid response from an upstream server while trying to fulfill the client's request. The client may have sent a perfectly valid request. The failure happened across a server-to-server boundary in the delivery path.

For testers, the key is topology. A browser sees one URL, but the request may pass through a CDN, load balancer, ingress proxy, API gateway, service mesh, and application. Any intermediary can be the gateway, and the next hop can be its upstream. Good 502 testing identifies those roles, injects controlled failures at the boundary, checks public behavior, and verifies whether the upstream performed any business work.

TL;DR

Treat 502 as a boundary failure, not a root-cause label. DNS, TLS, connection resets, protocol errors, malformed headers, and premature response closure can all produce similar client symptoms.

1. HTTP Status 502 Bad Gateway Semantics

A 502 response applies when a server, while acting as a gateway or proxy, receives an invalid response from an inbound server it contacted to fulfill the request. The status is about the intermediary's inability to use the upstream response. It does not say that the final application intentionally returned 502.

Examples include an upstream accepting a connection and closing it without a valid HTTP response, sending malformed response headers, speaking the wrong protocol on the configured port, failing a gateway-to-upstream TLS handshake, or terminating a response before required framing completes. Product infrastructure may map additional upstream communication failures to 502, so the edge contract and platform configuration must define expectations.

The word gateway is role-based. A service calling another service can act as a gateway even if the component is named backend. A CDN can be a gateway to an origin, and an ingress can be a gateway to a service. In a chain, one hop's upstream is another hop's downstream.

The response body is not standardized to one JSON shape. An API platform should provide a safe, consistent contract at its public edge. An HTML proxy page returned to a JSON consumer can be an integration defect even when 502 is the right status.

2. Map the Request Path Before Testing

Draw the actual path for the route under test. Include DNS, CDN, web application firewall, external load balancer, ingress, API gateway, service mesh sidecars, application, and any synchronous downstream service. Mark TLS termination, protocol conversion, retry ownership, timeouts, and correlation identifiers.

A compact map might be:

Client -> CDN -> ingress gateway -> orders service -> payment adapter
            TLS       HTTP/2             HTTPS

If the client receives 502, ask which component created it and which component was upstream at that hop. The ingress may fail to parse an orders-service response. Alternatively, the orders service may act as a gateway to the payment adapter and deliberately map that failure. These are different defects, dashboards, and teams.

Record environment differences. Local tests may bypass the CDN, use plain HTTP, or run only one instance. A staging proxy may rewrite errors differently from production. The minimum system test must pass through the components whose behavior the release depends on.

Use safe diagnostic response headers only in controlled environments. In production, correlate through a public request ID and restricted logs rather than exposing internal service names or IP addresses.

3. 502 vs 500, 503, and 504

Closely related 5xx codes describe different perspectives. Correct classification helps both clients and operators.

A single incident can generate several codes at different times. When all instances become unready, a load balancer may return 503. If one remaining instance accepts connections but emits invalid responses, the gateway may return 502. If it stalls, the gateway may return 504. If it responds with its own unhandled-exception payload, the edge may pass through 500.

Do not write one test that accepts any of these statuses unless the product truly makes no guarantee. Instead, inject a precise failure and assert the declared mapping. Review HTTP 500 vs 503 testing for internal failure and unavailability coverage.

4. Build a Controlled Upstream Test Double

A normal mock server usually emits valid HTTP and cannot reproduce protocol failures. For 502 paths, you may need a controllable upstream that can close a socket before headers, send a partial response, delay headers, present an untrusted test certificate, or return headers outside platform limits. Use it only in an isolated environment and keep payload sizes bounded.

Create one mode per fault so the test knows exactly what happened. Modes might be valid, close-before-response, partial-body, slow-headers, and invalid-protocol. Do not combine them randomly. Expose the selected mode through test process configuration or a protected control plane, never an unauthenticated production query parameter.

Place the double where the real upstream sits so the real gateway performs DNS, connection, TLS, protocol, buffering, and error mapping. A unit test of application exception handling cannot prove ingress behavior. Conversely, use lower-layer tests for rare malformed-byte cases so system suites remain stable.

After each fault, restore valid mode and assert recovery on a new connection. Check pool health because a gateway can retain a poisoned or half-closed connection. Clean up certificates, DNS overrides, network rules, and test routes.

5. Connection and Protocol Failure Scenarios

Cover failures by phase. Before connection, test a refused connection and controlled name-resolution failure if the platform maps them to 502. During TLS, test an expired or untrusted test certificate, hostname mismatch, unsupported policy, and certificate rotation only in an approved isolated setup. During request transmission, test upstream closure. During response, test premature closure before headers and after partial body.

Protocol configuration deserves explicit checks. An HTTP gateway pointed at an HTTPS port, or the reverse, receives bytes it cannot interpret. HTTP/2 negotiation and cleartext expectations can also differ across hops. Test supported protocol versions through the deployed configuration rather than assuming the client-to-edge protocol matches gateway-to-upstream.

Header problems include invalid syntax, duplicated framing fields, or limits exceeded by cookies and application metadata. Use minimal, safe cases. Do not turn a functional environment into an uncontrolled fuzz target. Security testing and parser fuzzing require separate authorization and safeguards.

For streaming responses, determine whether the gateway can still replace an upstream failure with 502 after client headers have been sent. It may instead terminate the downstream stream. Tests should assert the actual protocol-level behavior and ensure clients handle incomplete content without treating it as success.

6. Runnable Node.js Gateway Test

The following self-contained JavaScript test uses current Node.js built-in APIs. An upstream server can destroy its socket before sending a response. A small gateway uses fetch, maps that upstream failure to 502, and recovers when the upstream becomes healthy. Save it as bad-gateway.test.mjs and run node --test bad-gateway.test.mjs.

import test from 'node:test';
import assert from 'node:assert/strict';
import http from 'node:http';
import { once } from 'node:events';

async function listen(server) {
  server.listen(0, '127.0.0.1');
  await once(server, 'listening');
  return server.address().port;
}

test('gateway maps an unusable upstream response to 502 and recovers', async (t) => {
  let upstreamMode = 'valid';

  const upstream = http.createServer((request, response) => {
    if (upstreamMode === 'close') {
      request.socket.destroy();
      return;
    }
    response.writeHead(200, { 'content-type': 'application/json' });
    response.end(JSON.stringify({ source: 'upstream' }));
  });

  const upstreamPort = await listen(upstream);
  t.after(() => upstream.close());

  const gateway = http.createServer(async (request, response) => {
    try {
      const upstreamResponse = await fetch(
        `http://127.0.0.1:${upstreamPort}${request.url}`
      );
      const body = await upstreamResponse.text();
      response.writeHead(upstreamResponse.status, {
        'content-type': upstreamResponse.headers.get('content-type') ?? 'text/plain'
      });
      response.end(body);
    } catch {
      response.writeHead(502, { 'content-type': 'application/problem+json' });
      response.end(JSON.stringify({ title: 'Bad Gateway', status: 502 }));
    }
  });

  const gatewayPort = await listen(gateway);
  t.after(() => gateway.close());
  const url = `http://127.0.0.1:${gatewayPort}/resource`;

  upstreamMode = 'close';
  const failed = await fetch(url);
  assert.equal(failed.status, 502);
  assert.deepEqual(await failed.json(), { title: 'Bad Gateway', status: 502 });

  upstreamMode = 'valid';
  const recovered = await fetch(url);
  assert.equal(recovered.status, 200);
  assert.deepEqual(await recovered.json(), { source: 'upstream' });
});

This example is intentionally small. A production gateway must preserve required methods, bodies, headers, streaming, cancellation, and security rules. The test proves one classification branch, not a complete proxy implementation.

7. Verify Gateway Error Contracts and Headers

At the public boundary, assert the exact status, media type, stable error code, safe detail, and correlation identifier. Confirm a JSON API does not receive a branded HTML error generated by a default proxy configuration. Browser routes may intentionally serve HTML, so negotiate and test each client contract.

Review header behavior. The edge should add security and cache headers required for error responses. It should not leak upstream Server values, internal hostnames, private IPs, certificate detail, raw connection errors, or stack traces. A request ID returned to the client should correlate to edge logs and, where possible, upstream attempts.

Be careful with caching. A transient 502 should not remain cached beyond the declared policy and hide recovery. Send a unique URL to observe origin failure, then a stable URL to verify any intentional cache behavior. Test stale-if-error features only if the platform contract uses them. A cached successful representation served during an upstream failure is a different observable outcome from 502 and should carry appropriate freshness evidence.

Check cross-origin behavior for browser APIs. Error responses should preserve required CORS headers when policy allows the browser client to read the contract. Otherwise JavaScript may see only a network-style failure, while the network panel shows 502.

8. Retries and Ambiguous Upstream Outcomes

A gateway can retry some upstream failures, but each retry changes load and correctness risk. A connection failure before any bytes are sent may be safer than a reset after the upstream received a complete write. The gateway often cannot know whether business work committed before the response became unusable.

For reads, test the configured attempt count, per-attempt timeout, overall deadline, target selection, and final status. Verify retries do not exceed the client's deadline or multiply across CDN, gateway, SDK, and application layers. Layered retries can expand one user request into many upstream calls.

For writes, require an explicit replay-safety design. An idempotency key can let the upstream return the original outcome, but the gateway must forward it consistently. Test a commit followed by socket close, then retry or reconcile by the same key. Prove there is one order, charge, event, and audit outcome. The API idempotency testing guide provides a full matrix.

Clients should use bounded backoff and jitter only when operation policy permits retry. A 502 does not guarantee that immediate replay will help, and it does not guarantee that nothing happened.

9. DNS, TLS, and Certificate Rotation Tests

Many 502 incidents occur before application HTTP logic. For DNS, test that the gateway resolves the intended private name, honors the platform's update behavior, and handles controlled lookup failure according to policy. Avoid production host-file changes. Use an isolated zone or dependency address in a disposable environment.

For TLS, validate trust chain, hostname, validity period, protocol policy, and mutual TLS identity if used. Test certificate rotation with overlap: install the new trust or certificate, verify both sides during the planned window, rotate, then remove the old material. Confirm pooled connections and refreshed connections both behave as expected.

A test that disables certificate verification is not evidence that production TLS works. Keep verification enabled and use a test certificate authority trusted by the test gateway. Check clock synchronization because validity failures can look like sudden gateway errors.

Public 502 bodies should not expose certificate subjects or internal names. Restricted gateway logs should contain enough classified detail to distinguish DNS lookup, TCP connect, TLS handshake, protocol, and upstream response failures. This makes a single public code diagnosable without leaking topology.

10. Load Balancing, Pools, and Partial Failure

Test one bad upstream among healthy peers. Depending on retry and health policy, clients may see no error, occasional 502, or a temporary degradation. Verify that the bad target is removed after the documented threshold, healthy traffic continues, and it re-enters only after successful recovery checks. Avoid flapping caused by thresholds that are too sensitive.

Do not assert a fixed target order unless routing guarantees it. Use controlled target identities in a lower environment and assert aggregate outcomes. Check session affinity because a sticky client can repeatedly hit one bad target while aggregate dashboards look healthy.

Exercise stale pooled connections after deployment, rolling restart, keep-alive timeout mismatch, and graceful drain. A gateway can reuse a connection that the upstream has already closed, resulting in intermittent failures around idle boundaries. Verify safe retry rules and pool cleanup without masking unsafe writes.

In a multi-region design, confirm failure scope and failover policy. DNS or edge failover can add caching and propagation behavior. Keep the test bounded and coordinate operational changes. A functional test should never surprise on-call teams by intentionally removing shared capacity.

11. Observability and Fast 502 Triage

Correlate three views: the client-to-gateway request, the gateway's upstream attempt, and the upstream's own receipt and processing. Useful timings include DNS, connect, TLS, time to upstream headers, response duration, and retry attempts. Exact fields depend on the platform, but the diagnostic categories should be available.

Metrics should separate status by normalized route, gateway layer, upstream cluster, failure phase, region, and deployment without using unbounded raw IDs. Logs should record a safe request ID, selected upstream in restricted telemetry, classified failure, retry count, and byte milestones. Traces should preserve parent-child relationships across retries rather than making each attempt look like a separate client request.

When a 502 appears, ask:

1. Which component generated it?
2. Did it connect to the intended upstream?
3. Did TLS and protocol negotiation succeed?
4. Did the upstream receive the request?
5. Did the upstream send valid headers and a complete body?
6. Did any retry occur, and was it safe?
7. What business state exists now?
8. Did a deploy, certificate, DNS, or pool event coincide?

This sequence narrows the boundary quickly and prevents a vague frontend bug report.

12. HTTP Status 502 Bad Gateway Release Checklist

Map all gateway hops and record public error ownership. Verify valid traffic through the production-like path before injecting failures. Then cover refused connections, premature close, wrong protocol, relevant TLS faults, malformed or partial responses, pooled-connection recovery, one-bad-target behavior, and controlled full upstream loss.

Assert the public contract, security headers, CORS where applicable, cache behavior, and absence of internal detail. Confirm correlation across edge and upstream evidence. For writes, inject failures before receipt, after receipt, and after commit when possible, then prove final state and idempotent reconciliation.

Test retry budgets across every layer. Count resulting upstream attempts, apply deadlines, and verify cancellation. Exercise recovery without restarting the entire stack, plus deploy draining and certificate rotation. Ensure dashboards distinguish 502 from 500, 503, and 504.

Use API contract testing for gateway-to-service response expectations, but remember that conventional mocks rarely produce malformed transport behavior. Keep protocol fault tests at the integration layers that own the connection.

Interview Questions and Answers

Q: What does HTTP 502 Bad Gateway mean?

It means a gateway or proxy received an invalid response from an upstream server while fulfilling the request. I identify the generating gateway and upstream hop, reproduce a controlled boundary failure, verify safe external behavior, inspect final business state, and prove recovery.

Q: How is 502 different from 504?

502 means the upstream response was unusable, while 504 commonly means the gateway did not receive a timely response. A reset, protocol error, or malformed response can produce 502. A response deadline exceeded can produce 504.

Q: Can the upstream still process a request that ends as 502?

Yes. It may commit work and then close the connection or send an unusable response. That creates an ambiguous outcome, so I inspect authoritative state and test idempotency or operation lookup before any replay.

Q: How would you reproduce 502 in a test environment?

I place a controllable upstream double behind the real gateway and make it close before headers, send a partial response, use a test TLS failure, or speak the wrong configured protocol. Each mode is deterministic, protected, cleaned up, and paired with gateway and upstream evidence.

Q: What should a public 502 body contain?

It should follow the API's safe error schema with a stable code and correlation ID when promised. It should not contain internal hostnames, addresses, raw TLS errors, stack traces, proxy versions, or upstream credentials.

Q: Should a gateway retry after an upstream failure?

Only under an explicit policy that considers failure phase, method, idempotency, attempt budget, overall deadline, and target selection. Reads are generally easier than writes. I count upstream attempts and prove retries cannot multiply side effects.

Q: How do you diagnose intermittent 502 during deployments?

I correlate failures with readiness, drain events, connection-pool reuse, keep-alive settings, target identity, and deployment timing. I test long and idle connections through rolling restart, verify targets leave routing before termination, and check whether stale connections are retried safely.

Common Mistakes

• Reporting 502 as an application bug without identifying the gateway and upstream hop.
• Simulating an application 500 and assuming it covers malformed upstream transport behavior.
• Accepting 500, 502, 503, and 504 interchangeably in automation.
• Retrying writes after 502 without checking whether the upstream already committed them.
• Using a normal HTTP mock that cannot close sockets, break TLS, or emit partial responses.
• Testing with certificate verification disabled and calling the TLS path verified.
• Ignoring connection pools, keep-alive mismatch, draining, and one-bad-target scenarios.
• Leaking internal topology or raw proxy diagnostics in the public response.

Conclusion

A sound http status 502 bad gateway test treats the failure as a broken gateway-to-upstream exchange. Map the hops, control the upstream fault, assert the exact edge contract, and correlate both sides of the boundary.

The highest-risk case is an ambiguous write, where business work succeeds but the response fails. Combine transport fault injection with idempotency and final-state checks, then prove pool and target recovery. That approach turns an intermittent-looking 502 into a reproducible, diagnosable system test.

Interview Questions and Answers

Frequently Asked Questions

Related Guides

• HTTP 200 vs 201: What Testers Need to Know
• HTTP 204 no content: What Testers Need to Know
• HTTP 301 vs 302: What Testers Need to Know
• HTTP 400 vs 422: What Testers Need to Know
• HTTP 401 vs 403: What Testers Need to Know
• HTTP 404 vs 410: What Testers Need to Know