Perplexity API Timeout Error: Why Requests Hang

Most Perplexity timeouts are not failures. They are a client timeout that was copied from a plain chat completion API and applied to something that goes and reads the live web before it answers.

A timeout is not a response. Nothing came back, so nothing tells you whether the request reached Perplexity, whether it was processed, or whether something in between gave up first. Every other error hands you a status code to search for; this one hands you silence. That is why teams lose hours to it — the debugging instinct is to check the provider's status page, which is the layer least likely to be responsible.

Four layers can kill the request, and only one is Perplexity

Before changing any value, find out who enforced the limit. The shortest timeout in the chain wins, and it is almost never the one you configured — it is the one you inherited from a framework default or a hosting platform.

The round numbers in that second row are the most useful clue on this page. A request that dies at almost exactly 10, 29, 30 or 60 seconds was killed by infrastructure, not by a model. A Perplexity call that consistently dies at exactly your timeout value, while curl with a 120-second budget returns a full cited answer, is not an incident — it is retrieval doing its job for longer than you allowed.

Prove it with curl before you change code

Take your application entirely out of the picture. This runs the same request with a long ceiling and prints a full timing breakdown, so you can see where the seconds actually went:

curl -sS -o /dev/null --max-time 120 \
  -w "dns=%{time_namelookup}s connect=%{time_connect}s tls=%{time_appconnect}s firstbyte=%{time_starttransfer}s total=%{time_total}s\n" \
  https://api.perplexity.ai/chat/completions \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"sonar","messages":[{"role":"user","content":"ping"}]}'

Read it from the left. A large connect or tls figure is a network or handshake problem and has nothing to do with the model. A small connect with a large firstbyte means the connection was established instantly and Perplexity spent the time thinking — that is real processing latency, and the answer is a longer budget or a smaller request, not a retry. If the whole thing completes well inside your application's configured timeout, the request never had a chance and your own limit is the bug.

Why Perplexity is legitimately slower than a plain LLM call

Sonar models do retrieval. A single request runs searches, fetches candidate pages, ranks and reads them, then generates a grounded answer with citations. That is several network operations against third-party sites happening inside the window you are timing, and none of them are under Perplexity's control — one slow origin server is enough to stretch the whole call.

This makes the usual 10-second default badly wrong. Perplexity's own guidance for search-grounded requests is measured in tens of seconds, and complex queries or the research-grade models can legitimately run far longer than any general-purpose LLM timeout would allow. Teams that port a working OpenAI client over, keep the timeout, and swap the base URL see near-total failure and conclude the API is broken.

The variance matters as much as the mean. A narrow factual question may return in a few seconds while a broad multi-hop one takes ten times that, because it fetched ten times as many sources. Sizing a timeout from the average guarantees the tail fails; the correct approach is to size from p99, cap the work instead of the clock using parameters such as recency and domain filters, and stream so the user is not staring at nothing while the retrieval happens.

Set two timeouts, not one

A single overall deadline is the wrong shape for this problem. Connecting should be fast and failing to connect should fail immediately; generating can legitimately be slow. Collapsing both into one number means either network failures hang for the full budget, or slow-but-healthy requests get killed. Split them:

// Short connect budget, generous read budget.
async function callPerplexity(body: unknown) {
  const ac = new AbortController();
  const connectGuard = setTimeout(() => ac.abort(new Error('connect-timeout')), 5_000);
  const readGuard = setTimeout(() => ac.abort(new Error('read-timeout')), 60_000);

  try {
    const res = await fetch('https://api.perplexity.ai/chat/completions', {
      method: 'POST',
      signal: ac.signal,
      headers: {
        Authorization: `Bearer ${process.env.PERPLEXITY_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(body),
    });
    clearTimeout(connectGuard); // headers arrived — connection is alive
    if (!res.ok) throw new Error(`upstream ${res.status}`);
    return await res.json();
  } finally {
    clearTimeout(connectGuard);
    clearTimeout(readGuard);
  }
}

Then make sure the platform agrees with you. A 60-second client timeout inside a function capped at 10 seconds is decoration — the platform kills the invocation first and your carefully chosen value never applies. Raise the function's duration limit to sit above the client timeout, or move the call out of the request path entirely.

Streaming turns a total failure into a partial one

The single highest-leverage change is to stop waiting for the whole response. With stream: true the first bytes arrive quickly, which keeps every idle timer in the chain — proxies, load balancers, serverless runtimes — from concluding the connection is dead. Those idle timers are what kill most non-streaming calls long before the total duration cap is reached.

It also changes what failure costs. A buffered request that dies at the deadline returns nothing at all, and you pay for tokens the user never saw. A stream that breaks after several hundred tokens has already delivered something useful and gives you a point to resume from.

With streaming, replace the total deadline with an idle deadline that resets on every chunk. A request that has produced tokens two seconds ago is healthy no matter how long it has been running; one that has produced nothing for thirty seconds is stuck regardless of how recently it started:

// Idle timeout — resets whenever a chunk arrives.
const reader = res.body!.getReader();
let idle = setTimeout(() => reader.cancel('stalled'), 30_000);

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  clearTimeout(idle);
  idle = setTimeout(() => reader.cancel('stalled'), 30_000);
  yield value;
}
clearTimeout(idle);

Retries that help, and retries that make it worse

Timeouts are the most dangerous class of error to retry blindly, because you do not know what happened. The request may have failed instantly, or it may have been fully processed with the response lost on the way back — and retrying the second case pays for the work twice while adding load to a system that was already struggling.

• Retry on zero bytes received. Nothing was generated, so nothing is duplicated. This is the safe case.
• Do not blindly retry a mid-stream failure. Tokens were produced and billed; resume or degrade instead.
• Always use jitter. Fixed backoff synchronises every client into waves that arrive together and re-fail together.
• Cap attempts at two or three, then fail loudly. Unbounded retries turn a provider blip into a self-inflicted outage.
• Put a circuit breaker in front. When failures cross a threshold, stop calling for a cooling period — see the Perplexity failover guide.

And measure the right number. Averages hide timeouts completely: a p50 of 900 milliseconds tells you nothing about the 1% of requests sitting at your ceiling. Alert on p99 and on the timeout rate itself, because that tail is the entire population of users experiencing the bug.

Frequently Asked Questions

Related Perplexity Guides

• Is Perplexity Down? Outage Checking Guide
• Perplexity API Latency Guide
• Perplexity API Error Codes Reference
• Why Your Perplexity API Stream Breaks
• Perplexity API Rate Limits Explained
• Perplexity API Monitoring Guide
• Perplexity API CORS Error Explained