perplexity-common-errors

name	perplexity-common-errors
description	Diagnose and fix Perplexity Sonar API errors and exceptions. Use when encountering Perplexity errors, debugging failed requests, or troubleshooting integration issues. Trigger with phrases like "perplexity error", "fix perplexity", "perplexity not working", "debug perplexity", "perplexity 429".
allowed-tools	Read, Grep, Bash(curl:*)
version	1.12.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","perplexity","debugging"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

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

{