Perplexity API 502 Bad Gateway

A 502 is the only 5xx that is definitionally written by someone other than the component that failed. A gateway asked an upstream for a response, got something it could not use — an empty body, a reset connection, a malformed reply — and substituted an error of its own. Everything useful about a 502 follows from that one fact: your request was fine, the model may never have seen it, and the error you are reading was authored by a middleman.

Which middleman is the entire question. It might be Perplexity's own edge. It might equally be your ingress controller, a service-mesh sidecar, a corporate egress proxy, a CDN, or a routing library sitting between your code and the provider. These produce an identical status code and wildly different remediation, and teams routinely spend an incident refreshing a status page for a failure their own infrastructure emitted.

502 against the rest of the 5xx family

These five get filed together as “the API is broken” and then handed one retry policy, which guarantees that the policy is wrong for at least three of them. The column that matters is the last one, because it is the only one that changes what you do next.

502 and 504 are siblings and both are written by gateways — the difference is that a 504 means the intermediary waited and gave up, while a 502 means it got an answer it could not use. Neither tells you the upstream failed. The capacity case is covered separately in the Perplexity 503 guide, and the throttling case in the Perplexity 429 guide.

Why Perplexity returns 502 specifically

A Perplexity request does something no other provider on this list does: before a single token is generated, it goes and reads the live web. That retrieval fan-out has a long and fat latency tail, because it depends on third-party sites that Perplexity does not operate and cannot make faster. When a hard query pushes the retrieval leg past whatever read timeout the edge in front of the model holds, the edge does what edges do — it writes a 502 and closes the connection.

This gives Perplexity 502s a distinct signature: they correlate with query difficulty rather than with traffic volume. A broad research-style prompt that fans out across many sources will 502 at a rate a short factual prompt never does, at the same time of day, from the same key. If your 502 rate tracks prompt complexity instead of request rate, you are looking at retrieval, not capacity.

Sample rather than probe once. One request cannot distinguish a total failure from the far more common partial one, and the two call for different responses:

for i in $(seq 1 10); do
  curl -s -o /tmp/body -w "%{http_code} %{time_total}s %{content_type}\n" \
    https://api.perplexity.ai/chat/completions \
    -H "Authorization: Bearer $PPLX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"model":"sonar-pro","messages":[{"role":"user","content":"ping"}],"max_tokens":1}'
done

Three columns, three answers. The status code tells you whether it failed, the elapsed time tells you whether something waited before failing, and the content type tells you who wrote the error. Ten out of ten failing with a JSON body is an incident. Two out of ten failing with an HTML body is your own infrastructure having a moment, and no amount of provider failover will fix it.

The Perplexity trap: a 502 is a retrieval symptom, and thin citations are the early warning

Degradation here is visible before it becomes an error, and almost nobody instruments for it. As the retrieval half struggles, successful 200 responses start coming back with fewer citations, weaker sources, or none at all — and your code happily renders them because a 200 is a 200. The 502s arrive later, once the edge timeouts start tripping. Counting citations per response gives you a leading indicator of an incident that your error rate will not show for another ten minutes.

The corollary is a product decision worth making in advance: an answer that arrives ungrounded is not the product your users think they bought. Grade it as a soft failure, label it in the interface, and consider whether a slower well-cited answer beats a fast unsourced one for your use case. That framing turns a fuzzy quality problem into something you can alert on.

The streaming case, where the 502 never reaches your status-code metrics

If you stream, a large share of your gateway failures will never be counted as 502s at all. The response headers arrived long ago with a 200; the failure happens partway through the token stream, and what your client receives is a truncated event or an HTML error fragment spliced into a channel that was expecting server-sent events. Most SDKs raise that as a decoding error, so it lands in your logs as a parse failure in the JSON layer and your Perplexity error-rate panel stays flat through the entire incident.

• Assert on the terminal event. An iterator finishing is not the same as a stream completing. If the terminal marker never arrived, the response was truncated, whatever the status code said.
• Count partial responses as their own class. Not a success, not a 5xx. They behave differently and they are the metric that moves first.
• Record bytes and tokens received on failure. A stream that died at token three is a different problem from one that died at token three hundred, and only one of them is worth showing the user.
• Decide the resume policy in advance. Re-issuing the whole prompt is the honest default and it bills twice; showing the partial output with a visible label is often the better product answer.

A retry policy that fits a 502 specifically

502s are the most retry-friendly 5xx there is — they are usually brief, usually one hop, and usually gone by the time you look. That makes blanket “never retry 5xx” advice actively wrong here. Four rules keep the retry from becoming its own incident:

• One quick jittered retry first. Randomise across the full window rather than adding a small wobble, so a fleet of clients does not resynchronise and re-burst against the first recovered backend.
• Assume the work may have happened. The gateway could not read the response; that does not mean the upstream never produced one. Send an idempotency key for anything with a side effect, and expect that a retried completion can bill twice.
• Budget by ratio, not by count. Allow retries as a fraction of recent successes so the allowance collapses on its own when almost everything is failing — no deploy required. See the Perplexity retry budget guide.
• Retry against a deadline. If the user-facing request gave up eight seconds ago, attempt three is load on behalf of nobody. Propagate the deadline and skip attempts that cannot finish inside it.

If 502s persist past a handful of retries, they have stopped being transient and the failover machinery should take over — which only works if it was kept warm. The Perplexity failover guide covers keeping a second path tested rather than merely configured, and the circuit breaker guide covers stopping the retries automatically.

Frequently Asked Questions

Related Perplexity Guides

• Perplexity API 503 Service Unavailable
• Perplexity API 429 Too Many Requests
• Perplexity API 500 Internal Server Error
• Perplexity API Timeout Errors
• Perplexity API Error Codes Reference
• Perplexity Streaming Errors Guide
• Perplexity API Monitoring Guide