Execute Exa incident response procedures with triage, mitigation, and postmortem.
Use when responding to Exa-related outages, investigating errors,
or running post-incident reviews for Exa integration failures.
Trigger with phrases like "exa incident", "exa outage",
"exa down", "exa on-call", "exa emergency", "exa broken".
Rapid incident response procedures for Exa search API issues. Exa errors include a requestId field for support escalation. Default rate limit is 10 QPS. Contact [email protected] for urgent production issues.
Severity Levels
Level
Definition
Response Time
Example
P1
All Exa calls failing
< 15 min
401/500 on every request
P2
Degraded performance
< 1 hour
High latency, partial failures
P3
Minor impact
< 4 hours
Empty results, content fetch failures
P4
No user impact
Next business day
Monitoring gaps
Quick Triage (Run First)
set -euo pipefail
echo "=== Exa Triage ==="
# 1. Test API connectivity
echo -n "API Status: "
HTTP_CODE=$(curl -s -o /tmp/exa-triage.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":"triage test","numResults":1}')
echo "$HTTP_CODE"
# 2. Show error details if not 200
if [ "$HTTP_CODE" != "200" ]; then
echo "Error response:"
cat /tmp/exa-triage.json | python3 -m json.tool 2>/dev/null || cat /tmp/exa-triage.json
fi
# 3. Check if it's a key issue
echo ""
echo "API Key: ${EXA_API_KEY:+SET (${#EXA_API_KEY} chars)}"
Decision Tree
Exa API returning errors?
├── YES: What HTTP code?
│ ├── 401 → API key invalid/expired → Regenerate at dashboard.exa.ai
│ ├── 402 → Credits exhausted → Top up at dashboard.exa.ai
│ ├── 429 → Rate limited → Implement backoff, enable caching
│ ├── 5xx → Exa server issue → Retry with backoff, wait for resolution
│ └── 400 → Bad request → Fix request parameters
└── NO: Is search quality degraded?
├── Empty results → Broaden query, check date/domain filters
├── Low relevance → Switch search type, rephrase query
└── Slow responses → Switch to faster search type, add caching
Immediate Actions by Error Code
401/403 — Authentication
set -euo pipefail
# Verify API key
echo "Key present: ${EXA_API_KEY:+yes}"
echo "Key length: ${#EXA_API_KEY}"
# Test with a simple search
curl -v -X POST https://api.exa.ai/search \
-H "x-api-key: $EXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"auth test","numResults":1}' 2>&1 | grep "< HTTP"
# Fix: regenerate key at dashboard.exa.ai and update env
429 — Rate Limited
// Enable emergency caching to reduce API calls
import { LRUCache } from "lru-cache";
const emergencyCache = new LRUCache<string, any>({
max: 10000,
ttl: 30 * 60 * 1000, // 30-minute emergency TTL
});
// Reduce concurrent requests
import PQueue from "p-queue";
const queue = new PQueue({ concurrency: 3, interval: 1000, intervalCap: 5 });
