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

{"error": {"message": "Invalid API key", "type": "authentication_error", "code": 401}}

Causes: Key missing, expired, revoked, or doesn't start with

pplx-

Fix:

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.

429 Too Many Requests — Rate Limited

{"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:

async function withBackoff<T>(fn: () => Promise<T>, maxRetries = 5): Promise<T> {
  for (let i = 0; i <= maxRetries; i++) {
    try {
      return await fn();
    } catch (err: any) {
      if (err.status !== 429 || i === maxRetries) throw err;
      const delay = Math.pow(2, i) * 1000 + Math.random() * 500;
      console.log(`Rate limited. Retrying in ${delay.toFixed(0)}ms...`);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error("Unreachable");
}

See

perplexity-rate-limits

400 Bad Request — Invalid Model

{"error": {"message": "Invalid model: gpt-4", "type": "invalid_request_error"}}

Cause: Using a non-Perplexity model name.

Valid models:

sonar

sonar-pro

sonar-reasoning-pro

sonar-deep-research

400 Bad Request — Invalid search_domain_filter

{"error": {"message": "search_domain_filter must contain at most 20 domains"}}

Cause: Exceeding the 20-domain limit, or mixing allowlist (no prefix) with denylist (

-

Fix: Use either allowlist OR denylist mode, not both:

// Allowlist: only these domains
search_domain_filter: ["python.org", "docs.python.org"]

// Denylist: exclude these domains
search_domain_filter: ["-reddit.com", "-quora.com"]

Empty Citations Array

Not an error, but a common surprise.

Causes: Query too abstract, non-factual question, or model couldn't find relevant sources.

Fix:

// BAD: abstract query yields no citations
"Tell me about technology"

// GOOD: specific factual query
"What are the key features of TypeScript 5.5 released in 2025?"

Use

sonar-pro

sonar

Timeout / Hanging Request

Causes: Complex query with

sonar-pro

sonar-deep-research

Fix:

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 15000);

try {
  const response = await perplexity.chat.completions.create(
    { model: "sonar", messages: [{ role: "user", content: query }] },
    { signal: controller.signal }
  );
  return response;
} finally {
  clearTimeout(timeout);
}

402 Payment Required — No Credits

{"error": {"message": "Insufficient credits", "type": "billing_error"}}

Cause: Account has no API credits remaining.

Fix: Add credits at perplexity.ai/settings/api.

Diagnostic Commands

set -euo pipefail
# Quick API health check
curl -s -w "\nHTTP %{http_code} in %{time_total}s\n" \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"sonar","messages":[{"role":"user","content":"ping"}],"max_tokens":5}' \
  https://api.perplexity.ai/chat/completions

# Check if key env var is set
env | grep PERPLEXITY

# Test DNS resolution
dig api.perplexity.ai +short

Error Handling

invalid_request_error

authentication_error

billing_error

rate_limit_error

server_error

Output

• Identified error cause from HTTP status and error type
• Applied fix or workaround
• Verified resolution with diagnostic commands

Resources

• Perplexity Error Handling Guide
• API Reference

Next Steps

For comprehensive debugging, see

perplexity-debug-bundle