Perplexity API Error Codes Explained: 400, 401, 429, 5xx and Fixes

Perplexity's API is prepaid and search-backed, and both facts leak into its error codes: the two failures teams actually hit are an empty credit balance and a model name that was renamed out from under them.

The single most expensive mistake in Perplexity integrations is treating every non-200 the same way: one generic catch block, one blind retry loop. Half of Perplexity's error codes are deterministic — retrying them cannot succeed, it only burns quota and hides the real cause. This guide splits them into the ones you fix, the ones you wait out, and the ones you fail over on.

Every Perplexity API Error Code

Codes below are what Perplexity returns in production today. Response shapes drift as APIs version, so log the full body — the message text usually names the failing field, and that detail is what turns a 20-minute debug into a 20-second one.

The Perplexity Error That Wastes the Most Time

Perplexity is credit-metered rather than invoice-billed, so the error that stops most integrations is a 401 or 402 caused by a zero balance on an otherwise valid key. It looks identical to an authentication bug from the client side, which sends people rotating keys for an hour. Check the credit balance in API settings before you touch the key — and set a top-up alert, because unlike a rate limit, this failure never clears on its own.

Retry or Don't: The Decision Table

This is the part most error handling gets wrong. Retrying a deterministic error is strictly worse than failing fast — it delays the real signal and, on paid tiers, multiplies the bill.

Error Handling That Distinguishes All Three

One handler, three behaviours. The important line is the one that does not retry.

const FATAL = new Set([400, 401, 402, 404]);

async function callPerplexity(body, attempt = 0) {
  const res = await fetch('https://api.perplexity.ai/chat/completions', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${process.env.PERPLEXITY_API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });

  if (res.ok) return res.json();

  // Log the body once — it names the failing field on every 4xx
  const detail = await res.text();

  if (FATAL.has(res.status)) {
    throw new Error(`Perplexity error ${res.status} (not retryable): ${detail}`);
  }

  if (res.status >= 500) {
    // Perplexity-side: fail over rather than queue behind an outage
    if (attempt >= 1) return callFallbackProvider(body);
  }

  if (attempt >= 4) throw new Error(`Perplexity failed after retries: ${detail}`);

  const retryAfter = Number(res.headers.get('retry-after')) || 0;
  const backoff = retryAfter * 1000 || (2 ** attempt) * 500 + Math.random() * 500;
  await new Promise((r) => setTimeout(r, backoff));
  return callPerplexity(body, attempt + 1);
}

Note the fallback triggers on the second 5xx, not the first. A single 500 is often a one-off on a single host; two in a row is an incident, and that is the point where switching providers beats waiting.

Your Error or Theirs? A 60-Second Check

1. Read the status class. 4xx is you, 5xx is Perplexity. Nothing else in this list matters if you skip this step.
2. Log the response body. Perplexity names the offending field or model in the message — the status code alone is rarely enough.
3. Try a second API key. If a different key on a different account works, the problem is your account state or quota.
4. Try a different model. A working sibling model rules out an infrastructure-wide incident and points at naming, context length, or per-model capacity.
5. Check status.perplexity.com and live Perplexity monitoring for a confirmed incident before rolling back your own deploy.

For the outage-side playbook, see our Is Perplexity Down? guide. For quota specifically, the Perplexity rate limit guide covers headers and tier ceilings in depth.

Where to Send Traffic When Perplexity Returns 5xx

Fallbacks only help if they are configured before the incident. Each of these runs on independent infrastructure and an independent quota pool, so a Perplexity 503 does not follow you there.

Frequently Asked Questions

Related Perplexity Guides

• Is Perplexity Down? Outage Checking Guide
• Perplexity API Rate Limits Explained
• Perplexity API Monitoring Guide
• Perplexity Status Guide
• API Error Handling: The Complete Guide
• API Rate Limiting: The Complete Guide