Execute Perplexity incident response procedures with triage, mitigation, and postmortem.
Use when responding to Perplexity-related outages, investigating errors,
or running post-incident reviews for Perplexity integration failures.
Trigger with phrases like "perplexity incident", "perplexity outage",
"perplexity down", "perplexity on-call", "perplexity emergency", "perplexity broken".
Rapid incident response for Perplexity Sonar API issues. Perplexity-specific: the API depends on live web search, so outages can be partial (search degraded but API responding), model-specific (sonar-pro down but sonar working), or citation-related (answers returned but no sources).
API returning errors?
├─ 401/402: Auth issue
│ └─ Verify API key → Regenerate at perplexity.ai/settings/api
├─ 429: Rate limited
│ └─ Enable request queue → Reduce concurrency → Wait
├─ 500/503: Server error
│ ├─ All models affected?
│ │ ├─ YES → Perplexity outage. Enable fallback/cache.
│ │ └─ NO → Model-specific issue. Route to working model.
│ └─ Check Perplexity community forum for status
├─ Timeout: No response
│ ├─ DNS resolves? → Check network/firewall
│ └─ DNS fails? → DNS issue. Use alternative resolver.
└─ 200 but no citations: Search degraded
└─ Switch to sonar-pro for more citations
Immediate Actions
Auth Failure (401/402)
set -euo pipefail
# Verify current key
echo "Key prefix: ${PERPLEXITY_API_KEY:0:5}"
echo "Key length: ${#PERPLEXITY_API_KEY}"
# If key is invalid: regenerate at perplexity.ai/settings/api
# Update in secret manager:
# gcloud secrets versions add perplexity-api-key --data-file=<(echo -n "NEW_KEY")
# kubectl create secret generic perplexity-secrets --from-literal=api-key=NEW_KEY --dry-run=client -o yaml | kubectl apply -f -
# kubectl rollout restart deployment/your-app
Rate Limited (429)
set -euo pipefail
# Check if we're making too many requests
# Default limit: 50 RPM per API key
# Immediate: reduce concurrency
# kubectl set env deployment/your-app PERPLEXITY_MAX_CONCURRENT=1
# Enable request queuing if not already active
# kubectl set env deployment/your-app PERPLEXITY_QUEUE_MODE=true
Model-Specific Fallback
// If sonar-pro is failing, fall back to sonar
async function resilientSearch(query: string) {
try {
return await perplexity.chat.completions.create({
model: "sonar-pro",
messages: [{ role: "user", content: query }],
});
} catch (err: any) {
if (err.status >= 500) {
console.warn("sonar-pro unavailable, falling back to sonar");
return await perplexity.chat.completions.create({
model: "sonar",
messages: [{ role: "user", content: query }],
});
}
throw err;
}
}
