HTTP 502 Bad Gateway

HTTP 502 Bad Gateway indicates the server (or an upstream dependency) failed to fulfill a valid request. Treat it as a reliability signal: capture evidence, attribute the failure, and apply safe retry and backoff based on idempotency.

Try it (live endpoint)

Response includes the status code, standard headers (including Content-Type), and a small diagnostic JSON body describing the request and returned status.

curl -i "https://httpstatus.com/api/status/502"
Try in playground

Meaning

The server was acting as a gateway or proxy and received an invalid response from the upstream server.

What it guarantees
  • The server (or an upstream) failed to fulfill a valid request.
What it does NOT guarantee
  • The failure is permanent.
  • Immediate retries are always safe or effective.

When to use this status

  • Gateway/proxy failures reaching an upstream service.
  • CDN reverse proxy errors when origin health is degraded.
  • Service mesh/proxy issues during upstream deploys or incidents.

When NOT to use this status (common misuses)

Returning 5xx for client validation errors.
Clients retry unnecessarily; traffic spikes and costs increase.
Returning 500 without stable error identifiers/correlation.
SRE triage slows down; alerting becomes noisy and hard to act on.
Returning 503/504 without retry guidance.
Clients hammer the service or give up too early; cascading failures worsen.

Critical headers that matter

Content-Type
Defines error body format (JSON/text/problem+json).
Clients can’t parse structured errors; observability loses fidelity.
Cache-Control
Prevents caching transient errors unless intended.
CDNs cache failures; prolonged user-visible outages.

Tool interpretation

Browsers
Displays an error state; devtools exposes status and headers. Cache headers can accidentally cache error documents.
API clients
Classifies as failure; retry policy depends on idempotency and code class. Structured errors improve handling.
Crawlers / SEO tools
Persistent failures reduce crawl rate; soft-404 patterns cause indexing instability.
Uptime monitors
Typically alerts based on rate/threshold. Consistent classification reduces false positives.
CDNs / reverse proxies
May cache errors if misconfigured; respects Cache-Control and can serve stale on origin failure.

Inspector preview (read-only)

On this code, Inspector focuses on semantics, headers, and correctness warnings that commonly affect clients and caches.

Signals it will highlight
  • Status semantics vs method and body expectations
  • Header sanity (Content-Type, Cache-Control, Vary) and evidence completeness
  • Error cacheability and retry guidance signals
Correctness warnings
No common correctness warnings are specific to this code.

Guided Lab outcome

  • Reproduce HTTP 502 Bad Gateway using a controlled endpoint and capture the full exchange.
  • Practice distinguishing status semantics from transport issues (redirects, caching, proxies).
  • Learn to attribute failures to origin vs upstream and apply safe retry/backoff decisions.

FAQ

Should clients retry on HTTP 502?
Often yes for idempotent requests with backoff. Avoid blind retries for non-idempotent writes.
Is HTTP 502 cacheable?
Generally should not be cached unless explicitly intended; use Cache-Control to prevent sticky failures.
Which headers matter most for HTTP 502?
Content-Type and Cache-Control are the baseline. Some codes also require Location, WWW-Authenticate, or Retry-After.
How does this affect monitoring?
Server errors typically page based on rate/threshold; enrich with upstream attribution.
How does this affect crawlers/SEO?
Sustained 5xx reduces crawl rate and can drop pages from index.
What should error responses include?
A stable, machine-parseable format with correlation IDs and actionable messages.

Client expectation contract

Client can assume
  • The server or an upstream failed to fulfill the request.
Client must NOT assume
  • Immediate retries are always safe or effective.
Retry behavior
Retry idempotent requests with backoff; avoid retries for non-idempotent writes unless you have idempotency keys.
Monitoring classification
Server error
Alert on rate and duration; ensure CDNs do not cache transient failures.

Related status codes

501 Not Implemented
The server either does not recognize the request method, or it lacks the ability to fulfill the request.
503 Service Unavailable
The server is currently unavailable (overloaded, down for maintenance, or rate limiting). Should include Retry-After header when possible.
504 Gateway Timeout
The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.
500 Internal Server Error
A generic error message, given when an unexpected condition was encountered.

Explore more

Related guides
Related tools
Related utilities