502 Bad Gateway

Description

The 502 Bad Gateway status code indicates that the server, while acting as a gateway or proxy, received an invalid response from an upstream server it accessed while attempting to fulfill the request. This typically occurs in server architectures where multiple servers are involved in processing a request.

Common scenarios where a 502 Bad Gateway might occur include:

A proxy server or API gateway receives an invalid response from an upstream service
A load balancer cannot properly communicate with backend servers
A CDN (Content Delivery Network) cannot properly communicate with the origin server
Timeouts occur while communicating with upstream services
Upstream servers return malformed responses

The 502 error is distinct from other 5xx errors in that it specifically indicates a communication problem between servers, rather than an issue with the server directly handling the client's request.

Syntax

HTTP/1.1 502 Bad Gateway
Content-Type: application/json
Content-Length: 186

{
  "error": {
    "code": 502,
    "message": "Bad Gateway",
    "details": "The server received an invalid response from the upstream server while trying to fulfill the request."
  }
}

Examples

Example 1: API Gateway to Microservice Communication Failure

An API gateway attempts to forward a request to a microservice, but the microservice returns a malformed response.

Request:

GET /api/products/123 HTTP/1.1
Host: example.com
Accept: application/json

Response:

HTTP/1.1 502 Bad Gateway
Content-Type: application/json
Content-Length: 193

{
  "error": {
    "code": 502,
    "message": "Bad Gateway",
    "details": "The product service returned an invalid response while processing your request. Please try again later."
  }
}

Example 2: Proxy Server Timeout

A proxy server times out while waiting for a response from the origin server.

Request:

GET /api/reports/generate HTTP/1.1
Host: example.com
Accept: application/json

Response:

HTTP/1.1 502 Bad Gateway
Content-Type: application/json
Content-Length: 203

{
  "error": {
    "code": 502,
    "message": "Bad Gateway",
    "details": "The server timed out while waiting for a response from the upstream service. The operation might still be processing."
  }
}

Example 3: Load Balancer to Web Server Failure

A load balancer cannot properly communicate with backend web servers due to network issues.

Request:

POST /api/orders HTTP/1.1
Host: example.com
Content-Type: application/json
Content-Length: 124

{
  "product_id": "abc123",
  "quantity": 2,
  "shipping_address": {
    "country": "US",
    "zip": "10001"
  }
}

Response:

HTTP/1.1 502 Bad Gateway
Content-Type: application/json
Content-Length: 189

{
  "error": {
    "code": 502,
    "message": "Bad Gateway",
    "details": "We're experiencing communication issues with our backend servers. Please try again in a few minutes."
  }
}

Summary

The 502 Bad Gateway status code indicates a communication problem between servers in a multi-server architecture. It signals that the server acting as a gateway or proxy received an invalid response from an upstream server that it needed to access to complete the request.

Key points about 502 Bad Gateway:

It indicates a problem in server-to-server communication, not directly with the client's request
It's common in architectures involving proxies, gateways, load balancers, or microservices
It's often a temporary condition caused by network issues, timeouts, or server overloads
The issue might be with the upstream server, the network connection between servers, or the gateway itself
Unlike 500 Internal Server Error, it specifically points to a problem with inter-server communication
Clients can typically retry the request after a short delay
System administrators should check the health of upstream servers and network connections when seeing frequent 502 errors