Exa Advanced Troubleshooting
Overview
Deep debugging for complex Exa issues: latency spikes, intermittent failures, result quality degradation, and content retrieval failures. All Exa error responses include a requestId — always capture it.
Instructions
Step 1: Layer-by-Layer Diagnostics
import Exa from "exa-js";
interface DiagnosticResult {
layer: string;
success: boolean;
latencyMs: number;
details: string;
}
async function diagnoseExa(): Promise<DiagnosticResult[]> {
const results: DiagnosticResult[] = [];
const exa = new Exa(process.env.EXA_API_KEY);
// Layer 1: DNS + Network
let start = performance.now();
try {
const resp = await fetch("https://api.exa.ai", { method: "HEAD" });
results.push({
layer: "network",
success: true,
latencyMs: performance.now() - start,
details: `HTTP ${resp.status}`,
});
} catch (err: any) {
results.push({
layer: "network",
success: false,
latencyMs: performance.now() - start,
details: err.message,
});
return results; // No point continuing if network fails
}
// Layer 2: Authentication
start = performance.now();
try {
await exa.search("auth test", { numResults: 1 });
results.push({
layer: "auth",
success: true,
latencyMs: performance.now() - start,
details: "API key valid",
});
} catch (err: any) {
results.push({
layer: "auth",
success: false,
latencyMs: performance.now() - start,
details: `${err.status}: ${err.message}`,
});
if (err.status === 401 || err.status === 402) return results;
}
// Layer 3: Neural search
start = performance.now();
try {
const r = await exa.search("test neural search quality", {
type: "neural",
numResults: 3,
});
results.push({
layer: "neural-search",
success: true,
latencyMs: performance.now() - start,
details: `${r.results.length} results, top score: ${r.results[0]?.score.toFixed(3)}`,
});
} catch (err: any) {
results.push({
layer: "neural-search",
success: false,
latencyMs: performance.now() - start,
details: `${err.status}: ${err.message}`,
});
}
// Layer 4: Content retrieval
start = performance.now();
try {
const r = await exa.searchAndContents("content retrieval test", {
numResults: 1,
text: { maxCharacters: 500 },
highlights: { maxCharacters: 200 },
});
const hasText = !!r.results[0]?.text;
const hasHighlights = !!r.results[0]?.highlights?.length;
results.push({
layer: "content-retrieval",
success: hasText,
latencyMs: performance.now() - start,
details: `text: ${hasText}, highlights: ${hasHighlights}`,
});
} catch (err: any) {
results.push({
layer: "content-retrieval",
success: false,
latencyMs: performance.now() - start,
details: `${err.status}: ${err.message}`,
});
}
// Layer 5: findSimilar
start = performance.now();
try {
const r = await exa.findSimilar("https://nodejs.org", { numResults: 2 });
results.push({
layer: "find-similar",
success: r.results.length > 0,
latencyMs: performance.now() - start,
details: `${r.results.length} similar pages found`,
});
} catch (err: any) {
results.push({
layer: "find-similar",
success: false,
latencyMs: performance.now() - start,
details: `${err.status}: ${err.message}`,
});
}
return results;
}
// Print diagnostic report
const results = await diagnoseExa();
console.log("=== Exa Diagnostic Report ===");
for (const r of results) {
const icon = r.success ? "PASS" : "FAIL";
console.log(`[${icon}] ${r.layer}: ${r.latencyMs.toFixed(0)}ms — ${r.details}`);
}
