Exa Common Errors
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 hello@exa.ai.
Error Reference
400 — Bad Request
| Error Tag |
Cause |
Solution |
INVALID_REQUEST_BODY |
Malformed JSON or missing required fields |
Validate JSON structure and required query field |
INVALID_REQUEST |
Conflicting parameters |
Remove contradictory options (e.g., date filters with company category) |
INVALID_URLS |
Malformed URLs in getContents |
Ensure URLs have https:// protocol |
INVALID_NUM_RESULTS |
numResults > 100 with highlights |
Reduce to <= 100 or remove highlights |
INVALID_JSON_SCHEMA |
Bad schema in summary.schema |
Validate JSON schema syntax |
NUM_RESULTS_EXCEEDED |
Exceeds plan limit |
Check your plan's max results |
NO_CONTENT_FOUND |
No content at provided URLs |
Verify URLs are accessible |
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
| Error Tag |
Cause |
Solution |
NO_MORE_CREDITS |
Account balance exhausted |
Top up at dashboard.exa.ai |
API_KEY_BUDGET_EXCEEDED |
Spending limit reached |
Increase budget in API key settings |
403 — Forbidden
| Error Tag |
Cause |
Solution |
ACCESS_DENIED |
Feature not available on plan |
Upgrade plan or contact Exa |
FEATURE_DISABLED |
Endpoint not enabled |
Check plan capabilities |
ROBOTS_FILTER_FAILED |
URL blocked by robots.txt |
Use a different URL |
PROHIBITED_CONTENT |
Content blocked by moderation |
Review query for policy violations |
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
| Error Tag |
Cause |
Solution |
FETCH_DOCUMENT_ERROR |
URL could not be crawled |
Verify URL is accessible and not paywalled |
5xx — Server Errors
| Code |
Tag |
Action |
| 500 |
DEFAULT_ERROR / INTERNAL_ERROR |
Retry after 1-2 seconds |
| 501 |
UNABLE_TO_GENERATE_RESPONSE |
Rephrase query (answer endpoint) |
| 502 |
Bad Gateway |
Retry with delay |
| 503 |
Service Unavailable |
Check status page, retry later |
Content Fetch Errors (per-URL status in getContents)
| Tag |
Cause |
Resolution |
CRAWL_NOT_FOUND |
Content unavailable at URL |
Verify URL correctness |
CRAWL_TIMEOUT |
Fetch timed out |
Retry or increase livecrawlTimeout |
CRAWL_LIVECRAWL_TIMEOUT |
Live crawl exceeded timeout |
Set livecrawlTimeout: 15000 or use livecrawl: "fallback" |
SOURCE_NOT_AVAILABLE |
Paywalled or blocked |
Try cached content with livecrawl: "never" |
UNSUPPORTED_URL |
Non-HTTP URL scheme |
Use standard HTTPS URLs |
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
- Check the HTTP status code from the error response
- Match the error tag to the tables above
- Apply the documented solution
- Include
requestId from error responses when contacting support
Resources
Next Steps
For comprehensive debugging, see exa-debug-bundle. For rate limit patterns, see exa-rate-limits.
Source: jeremylongshore/claude-code-plugins-plus-skills → skills/.curated/exa-common-errors/SKILL.md
Also appears in: jeremylongshore/claude-code-plugins-plus-skills/plugins/saas-packs/exa-pack/skills/exa-common-errors/SKILL.md
thedixitjain