Identify and avoid Perplexity anti-patterns and common integration mistakes.
Use when reviewing Perplexity code, onboarding new developers,
or auditing existing integrations for best practices violations.
Trigger with phrases like "perplexity mistakes", "perplexity anti-patterns",
"perplexity pitfalls", "perplexity code review", "perplexity gotchas".
Identify and avoid Perplexity anti-patterns and common integration mistakes.
Use when reviewing Perplexity code, onboarding new developers,
or auditing existing integrations for best practices violations.
Trigger with phrases like "perplexity mistakes", "perplexity anti-patterns",
"perplexity pitfalls", "perplexity code review", "perplexity gotchas".
allowed-tools
Read, Grep
version
1.12.0
license
MIT
author
Jeremy Longshore <jeremy@intentsolutions.io>
tags
["saas","perplexity","audit"]
compatibility
Designed for Claude Code, also compatible with Codex and OpenClaw
Perplexity Known Pitfalls
Overview
Real gotchas when integrating Perplexity Sonar API. Perplexity uses an OpenAI-compatible chat endpoint but performs live web searches -- a fundamentally different paradigm from standard LLM completions. These pitfalls come from treating it like a regular chatbot.
Prerequisites
Perplexity API key configured
Understanding of OpenAI-compatible chat API format
Pitfalls
1. Using It as a Generic Chatbot
Perplexity searches the web per request. Using it for tasks that don't need web search wastes money.
# BAD: general chatbot (wastes a search query)
response = call_perplexity("Write me a haiku about cats")
# Costs $0.005+ for something any LLM can do offline# GOOD: leverage web search capability
response = call_perplexity(
"What are the latest Next.js 15 features released this month?",
search_recency_filter="month"
)
2. Ignoring Citations
Perplexity returns [1], [2] markers in text with a separate citations array. Ignoring them loses the key value prop.
data = response.model_dump() # or response.json() for raw HTTP
answer = data["choices"][0]["message"]["content"]
citations = data.get("citations", []) # NOT in choices — top-level field# BAD: displaying raw markersprint(answer) # "According to [1], Node.js 22 adds..."# GOOD: replace markers with linksimport re
for i, url inenumerate(citations, 1):
answer = answer.replace(f"[{i}]", f"{i}")
3. Using Wrong SDK Import
There is no @perplexity/sdk or Python package. Use the standard OpenAI client.
perplexity
// BAD — this package doesn't existimport { PerplexityClient } from"@perplexity/sdk";
// GOOD — use OpenAI client with Perplexity base URLimportOpenAIfrom"openai";
const client = newOpenAI({
apiKey: process.env.PERPLEXITY_API_KEY,
baseURL: "https://api.perplexity.ai",
});
4. Not Setting max_tokens
Without max_tokens, responses can be arbitrarily long, increasing costs unpredictably.
// BAD: no token limit — output cost can spikeawait client.chat.completions.create({
model: "sonar-pro", // $15/M output tokens!messages: [{ role: "user", content: "Tell me about AI" }],
});
// GOOD: always set max_tokensawait client.chat.completions.create({
model: "sonar-pro",
messages: [{ role: "user", content: "Tell me about AI" }],
max_tokens: 1024,
});
5. No Recency Filter for Time-Sensitive Queries
Without search_recency_filter, Perplexity may cite outdated articles.
# BAD: may return articles from any time period
response = call_perplexity("current Bitcoin price")
# GOOD: constrain to recent results
response = call_perplexity(
"current Bitcoin price",
search_recency_filter="day"# hour | day | week | month
)
6. Sending Full Conversation History
Each message in the conversation may trigger new search queries. Sending 20 turns of history is expensive and slow.
# BAD: 20 turns of history = many search queries
messages = long_history + [{"role": "user", "content": "summarize"}]
# GOOD: summarize context, send focused query
messages = [
{"role": "system", "content": "Answer based on web search."},
{"role": "user", "content": f"Context: {summary}\nQuestion: {question}"}
]
7. Using sonar-pro for Simple Queries
sonar-pro costs 3-15x more than sonar. Using it for simple factual lookups wastes budget.
// BAD: sonar-pro for a trivial questionawait client.chat.completions.create({
model: "sonar-pro", // $3 input + $15 output per M tokensmessages: [{ role: "user", content: "What is the capital of France?" }],
});
// GOOD: match model to complexityconst model = isComplexQuery(query) ? "sonar-pro" : "sonar";
8. Mixing Allowlist and Denylist in Domain Filter
search_domain_filter supports either allowlist (include) or denylist (exclude with - prefix), but not both in the same request.
