Exa Common Errors

Prerequisites

• A bounded non-sensitive reproduction, environment/version, expected behavior, and redaction rule for diagnostics.

Output

• A classified Exa failure with redacted evidence and a verified bounded remediation or escalation.

Error Handling

Examples

For a failing request, record correlation ID, environment, status class, latency, and sanitized request category, then validate credentials and options against a non-sensitive fixture. Escalate with redacted evidence rather than full query/result content.

Overview

Quick reference for Exa API errors by HTTP status code and error tag. All error responses include a requestId field — include it when contacting Exa support at [email protected].

Error Reference

400 — Bad Request

401 — Unauthorized

# Verify your API key is set and valid
echo "Key set: ${EXA_API_KEY:+yes}"

# Test with curl
curl -s -o /dev/null -w "%{http_code}" \
  -X POST https://api.exa.ai/search \
  -H "x-api-key: $EXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"test","numResults":1}'

Fix: Regenerate API key at dashboard.exa.ai.

402 — Payment Required

403 — Forbidden

429 — Rate Limited

// Default rate limit: 10 QPS (queries per second)
// Error response format: { "error": "rate limit exceeded" }

// Fix: implement exponential backoff
async function searchWithBackoff(exa: Exa, query: string, opts: any) {
  for (let attempt = 0; attempt < 5; attempt++) {
    try {
      return await exa.search(query, opts);
    } catch (err: any) {
      if (err.status !== 429) throw err;
      const delay = 1000 * Math.pow(2, attempt) + Math.random() * 500;
      console.log(`Rate limited. Waiting ${delay.toFixed(0)}ms...`);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error("Rate limit retries exhausted");
}

422 — Unprocessable Entity

5xx — Server Errors

Content Fetch Errors (per-URL status in getContents)

Quick Diagnostic Script

set -euo pipefail

echo "=== Exa Diagnostics ==="
echo "API Key: ${EXA_API_KEY:+SET (${#EXA_API_KEY} chars)}"

# Test basic connectivity
echo -n "API connectivity: "
HTTP_CODE=$(curl -s -o /tmp/exa-test.json -w "%{http_code}" \
  -X POST https://api.exa.ai/search \
  -H "x-api-key: $EXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"connectivity test","numResults":1}')
echo "$HTTP_CODE"

if [ "$HTTP_CODE" != "200" ]; then
  echo "Error response:"
  cat /tmp/exa-test.json | python3 -m json.tool 2>/dev/null || cat /tmp/exa-test.json
fi

Instructions

1. Check the HTTP status code from the error response
2. Match the error tag to the tables above
3. Apply the documented solution
4. Include requestId from error responses when contacting support

Resources

• Exa Error Codes
• Exa Rate Limits
• Exa Status Page

Next Steps

For comprehensive debugging, see exa-debug-bundle. For rate limit patterns, see exa-rate-limits.