When you see this status
- Proxy forwards request to unhealthy backend
- Upstream service crashes mid-response
- Network partition between proxy and backend
- Backend returns malformed HTTP response
- Timeout occurs waiting for backend response
Common causes
- Backend server crashes or overload
- Network connectivity issues
- Misconfigured proxy/gateway
- Backend sends invalid HTTP headers
- Upstream service returns non-HTTP response
How to debug it
- Check backend server health/availability
- Inspect proxy/gateway logs for errors
- Verify network connectivity to backend
- Test backend endpoint directly
- Monitor backend response times
Return this code in your framework
Express (Node.js)
app.get('/proxy', (req, res) => { res.status(502).send('Bad Gateway'); });
FastAPI (Python)
from fastapi import FastAPI; app = FastAPI(); @app.get('/') async def root(): return Response(status_code=502);
NestJS
import { Controller, Get, HttpCode } from '@nestjs/common'; @Controller() export class AppController { @Get() @HttpCode(502) getBadGateway() { return 'Bad Gateway'; } }
Go (net/http)
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusBadGateway); });
About HTTP 502
HTTP status code 502 Bad Gateway is part of the
5xx Server Error family. Gateway or proxy received an invalid response from upstream server. Understanding it is essential for
backend engineers, API designers, and anyone debugging integrations between services.
The Qaynaq Labs HTTP Status Code Explainer covers all standard codes with practical guidance:
what triggers them, how to debug them in production, and exactly how to return them from common
frameworks. Each code page is hand-curated and verified.