perplexity-common-errors

# Perplexity Common Errors ## Overview Quick reference for the most common Perplexity Sonar API errors, their root causes, and fixes. All Perplexity errors follow the OpenAI error format since the API is OpenAI-compatible. ## Prerequisites - `PERPLEXITY_API_KEY` environment variable set - `curl` available for diagnostic commands ## Error Reference ### 401 Unauthorized — Invalid API Key ```json {"error": {"message": "Invalid API key", "type": "authentication_error", "code": 401}} ``` **Causes:** Key missing, expired, revoked, or doesn't start with `pplx-`. **Fix:** ```bash set -euo pipefail # Verify key is set and has correct prefix echo "${PERPLEXITY_API_KEY:0:5}" # Should print "pplx-" # Test key directly curl -s -o /dev/null -w "%{http_code}" \ -H "Authorization: Bearer $PERPLEXITY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"sonar","messages":[{"role":"user","content":"test"}],"max_tokens":5}' \ https://api.perplexity.ai/chat/completions # 200 = valid, 401 = invalid key ``` Regenerate at [perplexity.ai/settings/api](https://www.perplexity.ai/settings/api). --- ### 429 Too Many Requests — Rate Limited ```json {"error": {"message": "Rate limit exceeded", "type": "rate_limit_error", "code": 429}} ``` **Causes:** Exceeded requests per minute (RPM). Most tiers allow 50 RPM. Perplexity uses a leaky bucket algorithm. **Fix:** ```typescript async function withBackoff<T>(fn: () => Promise<T>, maxRetries = 5): Promise<T> { for (let i = 0; i <...