Perplexity API Incident Postmortem: Reconstructing an Outage You Have No Logs For

Almost everything written about incident reviews assumes you own the thing that broke. You read your own logs, you find the deploy or the query or the config change, and the fix is a pull request. A Perplexity API outage inverts that completely: the interesting half of the system is behind someone else's network boundary, it emits no telemetry you can read, and the only public artifact it will ever produce is a status page entry written for customers rather than for investigators.

That does not make the postmortem impossible. It makes it a different document, with a different subject. The vendor's failure is an input to your incident; the incident itself is what your system did when that input arrived. Detection time, blast radius, retry amplification, whether the fallback anyone documented had ever been executed — all of that is yours, all of it is measurable, and all of it is fixable without a single conversation with the provider.

The Evidence Asymmetry You Are Writing Around

Start by being explicit about what can and cannot be known, because postmortems for third-party outages go wrong when they quietly promise a level of certainty the evidence does not support. Here is the honest split.

The last row is where most third-party postmortems stall. A review gets scheduled, the vendor has not published anything, and the document sits in draft waiting for a root cause that in many cases never arrives. Ship the postmortem without it. Four of the six rows above are fully yours, they contain every action item you can actually execute, and none of them depend on the vendor saying anything at all.

status.perplexity.ai Is Not a Timeline

Status pages are written by people, after an internal signal crosses a threshold and someone confirms it is real and decides it is customer-visible. Every one of those steps costs time, and each one is a place where a degradation that was very real for you fails to become a public entry.

None of this is an accusation of bad faith — a status page is a communication tool for a whole customer base and it is doing its job. It is simply the wrong instrument for the measurement you are making. Use it for exactly one thing: corroboration, in a line of the timeline that reads “provider acknowledged at HH:MM, forty minutes after our onset”. That gap is itself a finding, and it is the number that tells you how much independent detection you need to own.

The Perplexity Trap: The Outage Has No Status Codes In It

Perplexity's API is a retrieval system with a model attached, and that changes the shape of its failures. The distinctive Perplexity incident is not a wave of 500s. It is a window during which every request returns 200, in normal time, with a well-formed body — and the retrieval layer behind it was degraded, so the answers are thinner, the citation lists are shorter or empty, and the content is staler than the question required.

A timeline built from status codes and latency percentiles is structurally blind to this. It will show a flat, healthy green line across the exact window your users were complaining about, and the postmortem will conclude that the reports were anecdotal. The only way to have evidence is to have been recording answer-shaped signals all along: citations returned per response, share of responses with zero citations, response length distribution, and the age of the newest source cited. None of those can be backfilled after the fact.

So the honest finding in a lot of Perplexity postmortems is a measurement gap rather than a cause. Write it that way. “We cannot determine whether retrieval was degraded during this window because we do not record citation counts” is a real, actionable conclusion that produces a specific piece of work. “No provider incident found” is a conclusion that produces nothing and guarantees the same investigation happens again next quarter.

Record the Ledger Now, Not During the Incident

Every postmortem you will ever write for Perplexity is limited by what a single function emitted months earlier. This is the whole game: the investigation is decided in advance, by the fields you chose to log around the call, and no amount of diligence during the review can add a field that was never written.

// One record per Perplexity attempt. Emitted whether it succeeded or not —
// the failures are the postmortem, and a log that only records successes
// is a log that is blank for the exact window you need it.

async function callPerplexity(endpoint, body, ctx) {
  const startedAt = Date.now();
  let res, err = null;
  try {
    res = await fetch('https://api.perplexity.ai' + endpoint, {
      method: 'POST',
      headers: { Authorization: 'Bearer ' + process.env.PERPLEXITY_API_KEY },
      body: JSON.stringify(body),
      signal: AbortSignal.timeout(ctx.deadlineMs),
    });
  } catch (e) {
    err = e;
  }

  emit('provider_request', {
    ts: startedAt,
    // Derive from the base URL, never from the client class name — a
    // compatibility-shim client will otherwise log the wrong vendor.
    provider: 'perplexity',
    // Model id, not just provider. A per-model degradation is invisible
    // without this, and it is the most common shape of incident.
    model: body.model,
    endpoint,
    status: res ? res.status : 0,
    error_class: err ? err.name : null,
    latency_ms: Date.now() - startedAt,
    // The provider's OWN request id. This is the single highest-value
    // field here: it is the only identifier vendor support can act on,
    // and it cannot be reconstructed from anything else you have.
    provider_request_id: res ? res.headers.get('x-request-id') : null,
    attempt: ctx.attempt,
    breaker_state: ctx.breakerState,
    // Which product feature this call was serving, so impact can be
    // stated in user terms rather than in request counts.
    feature: ctx.feature,
  });

  if (err) throw err;
  return res;
}

Three fields carry most of the weight and are the three most often missing. provider_request_id is the only thing that makes a support conversation productive; without it you are describing an outage in prose to someone who indexes by id. attempt is what separates “the provider saw 8,000 failures” from “the provider saw 2,000 failures and we turned them into 8,000”, which is a finding about your own retry policy. And feature is what lets the impact section say which part of the product stopped working instead of quoting a request count that means nothing to anyone outside the team.

The Six Facts, In Order

A third-party postmortem is a short document with a fixed spine. Establish these six in this order and the findings write themselves; skip straight to the vendor's root cause and you will produce three pages that change nothing.

1. Onset. The first minute your own Perplexity error rate or latency distribution left its normal band. From your ledger, to the minute, with the metric named.
2. Detection. When a human first knew. Record the mechanism honestly — an alert, a colleague in Slack, or a customer. Detection minus onset is the number this document exists to reduce.
3. Signature. What the failure actually looked like: status codes, error classes, latency shape, which models and endpoints, and crucially whether responses were failing or merely wrong. Several provider degradations return 200 throughout.
4. Response. What your system did automatically — retried, tripped a breaker, failed over, queued, or piled up — and what humans did after that. This is where retry amplification and untested fallbacks surface.
5. Impact. In product terms and, where a dedicated or provisioned resource was involved, in currency. “Document ingestion was unavailable for 52 minutes, affecting 1,900 uploads” travels; “4.2% of API calls failed” does not.
6. Provider account. Last, not first. What status.perplexity.ai said and when, quoted with a capture timestamp, plus any published root cause. If nothing was published, write “no provider statement as of <date>” and ship the document.

Note what is deliberately absent: a five-whys chain into the provider's infrastructure. You cannot conduct one, and the imitation of one — speculating about their capacity planning — is the part of these documents that ages worst. The five whys still apply, just pointed at your own side: why did this take nineteen minutes to detect is a question you can answer all the way down.

Symptoms That Get Attributed to the Wrong System

The reason detection times on provider incidents are so bad is that a dependency degradation rarely announces itself as a dependency degradation. It arrives dressed as one of your own bugs, and teams spend the first half of the incident debugging the wrong layer. Five of the six rows below involve responses that a naive monitor reads as healthy.

Write this table's relevant row into the postmortem as its own finding. “Twenty-three minutes were spent investigating our own queue consumer because the dependency was returning 200s” is precise, blameless, and produces an obvious piece of work: alert on the latency distribution of provider calls, not only on their failures.

Action Items You Can Actually Own

The test for every line in the action items section: does it have an owner on your team and a definition of done? “Escalate reliability concerns with Perplexity” fails both. These pass.

• Cut detection time. Alert on provider error rate and latency percentiles per model, with a minimum-volume floor so low-traffic endpoints do not page on two failures. Done when a synthetic degradation pages within the target.
• Contain the blast radius. A bounded concurrency limit for Perplexity calls, so a slow dependency cannot exhaust shared workers and take down features that never touch it. Done when a fault-injection test slows Perplexity to the deadline and unrelated endpoints stay healthy — see the circuit breaker guide.
• Cap retry amplification. A retry budget expressed as a ratio of successful traffic rather than a per-call attempt count, so a total outage cannot multiply your own load. Done when the ledger's attempt field shows a bounded ratio during a simulated outage — see the retry budget guide.
• Exercise the fallback. Route a small share of real production traffic to the documented alternative on a schedule. Done when the last successful execution is dated and recent. An untested fallback is a paragraph, not a control.
• Close the evidence gaps this postmortem exposed. Every “we could not determine” in the document becomes a logging ticket. This is the item that makes the next postmortem cheap, and it is the one most reliably dropped.
• Record the vendor-facing follow-up separately. Support ticket ids and provider request ids are worth tracking, but keep them out of the action item list — they have no completion criteria you control, and mixing them in is how a review gets marked incomplete for months.

Where Traffic Should Have Gone

Almost every Perplexity postmortem ends at the same finding: an alternative existed on paper and was never exercised. Each of these runs on separate infrastructure and separate credentials, so a Perplexity incident does not follow you there.

Deciding which destination is worth the same answer is its own problem — see the fallback ranking guidefor how to rank them, and the failover guidefor the cutover mechanics.

Frequently Asked Questions

Related Perplexity Guides

• Perplexity API Monitoring Guide
• Perplexity API Status Alerts
• Perplexity API Error Codes Explained
• Perplexity API Circuit Breaker Guide
• Perplexity API Retry Budget Guide
• Perplexity API SLA & Uptime
• Incident Postmortem Guide (your own services)