Perplexity API 504 Gateway Timeout

A 504 is a statement about a clock, not about a failure. Some intermediary decided in advance how long it was willing to wait, the answer did not arrive inside that window, and the intermediary wrote an error of its own. Nothing in the status code tells you that Perplexity failed. It tells you that a deadline expired, and deadlines are configuration — which means the fault is findable by reading a number rather than by guessing.

Whose clock is the whole question. It might be Perplexity's edge. It might just as easily be your ingress controller, a service-mesh sidecar, a corporate egress proxy, a platform request limit, or the timeout argument you passed to your own SDK three releases ago and have not looked at since. These produce an identical status code and entirely different remediation.

504 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 the policy is wrong for at least three of them. The last column is the one that matters, because it is the only one that changes what you do next.

502 and 504 are the two gateway-authored codes and they are routinely conflated. The difference is simple and it changes your diagnosis: a 502 means the gateway got an answer it could not use, so the evidence is in the response body; a 504 means it got nothing and stopped waiting, so the evidence is in the elapsed time. The unusable-reply case is covered in thePerplexity 502 guide, the capacity case in thePerplexity 503 guide, and throttling in thePerplexity 429 guide.

Why Perplexity returns 504 specifically: you are timing a web crawl, not a generation

Every other provider on this list answers from weights. Perplexity answers from weights plus the live web: a request triggers a search, a fan-out of fetches against external sites, and only then a generation grounded in what came back. That architecture is the product, and it is also the entire explanation for its timeout behaviour, because the request's total latency is bounded below by the slowest external page it decided to read.

This inverts the usual relationship between load and failure. On a conventional inference API, timeouts correlate with request rate — more traffic, more queueing, more deadline expiry. On Perplexity, they correlate with prompt complexity. A broad, recent, multi-entity question triggers a wider fan-out than a narrow one, and a single slow or unresponsive source in that fan-out can hold the whole request open. Your quiet Sunday can produce more 504s than your busy Tuesday if the questions asked on Sunday were harder.

The consequence for deadline-setting is that a single timeout value applied to all requests is guaranteed to be wrong in both directions: too short for genuinely research-shaped queries and too long for lookups that should have returned in a second. If your product has both shapes, they need different deadlines, and the classification has to happen before the request rather than after it fails.

Sample rather than probe once, and record all three columns. One request cannot tell a total failure apart from the far more common partial one:

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

The status code says whether it failed, the elapsed time says which timer expired, and the content type says who wrote the error. Set --max-time deliberately higher than the deadline you are investigating, otherwise curl becomes the shortest timer in the path and you measure your own probe instead of the system.

The Perplexity warning sign: thin citations on a 200 precede the 504s

The most useful Perplexity-specific metric is not the error rate, it is the citation count on successful responses. When retrieval is degraded — sources timing out, fan-out returning less — the first thing that happens is not a failure. It is a 200 that came back suspiciously fast with two citations where it normally has eight. That response is materially worse for your users and your dashboards will score it as a success.

Record the number of citations on every response and alert on the distribution rather than on errors alone. A collapse in median citation count is the leading indicator; the 504s, when they arrive, are the lagging one. This is the single highest-value instrumentation choice specific to this provider, and almost nobody makes it.

When you do set deadlines, set them against the retrieval tail rather than the median. Measure your own p95 for research-shaped prompts and put the deadline above it, then handle expiry as a product state — a visible “still searching” affordance — rather than as an error. Retrying a research query that timed out will usually take just as long the second time, because the slow source is still slow.

The streaming case, where the 504 stops happening at all

Streaming is the most underrated fix for 504s, and it works for a reason that is easy to miss: most gateway timeouts are idle timeouts rather than total-duration limits. They fire when no bytes have moved for N seconds, not when the request has been open for N seconds. A streamed response puts bytes on the wire as soon as the first tokens exist, which resets the idle timer continuously and keeps a long generation alive under a deadline that would have killed the buffered equivalent.

• Check which kind of timeout you have. An idle timeout is defeated by streaming; a hard request-duration cap is not. They are configured separately and confusing them wastes a day.
• 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 no matter what the status code said.
• Count partial responses as their own class. Not a success, not a 5xx. On a streamed path they are the metric that moves first, and a status-code-only dashboard stays flat through the entire incident.
• 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 504 specifically

504 is the 5xx where the standard retry advice is most likely to hurt you, because the one thing a 504 does not tell you is whether the work happened. Four rules keep the retry from becoming its own incident:

• Assume the request may have succeeded. Your gateway stopped listening; the upstream did not necessarily stop working. Send an idempotency key for anything with a side effect, and expect a retried completion to be billable twice.
• Do not retry into the same deadline. If the timeout was too short for this request, a second identical attempt will expire identically. Change something — stream it, shrink it, or route it to a path with a longer deadline — or do not retry at all.
• 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, with no deploy required. See the Perplexity retry budget guide.
• Retry against a deadline, not a counter. 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 504s persist past a couple of attempts they have stopped being transient, and the failover machinery should take over — which only works if it was kept warm. ThePerplexity failover guidecovers keeping a second path tested rather than merely configured, and thecircuit breaker guidecovers stopping the retries automatically.

Frequently Asked Questions

Related Perplexity Guides

• Perplexity API 502 Bad Gateway
• Perplexity API 503 Service Unavailable
• Perplexity API Timeout Errors
• Perplexity API 429 Too Many Requests
• Perplexity API Latency Guide
• Perplexity Streaming Errors Guide
• Perplexity API Error Codes Reference
• Perplexity API Monitoring Guide