exa-common-errors

name	exa-common-errors
description	Diagnose and fix Exa API errors by HTTP code and error tag. Use when encountering Exa errors, debugging failed requests, or troubleshooting integration issues. Trigger with phrases like "exa error", "fix exa", "exa not working", "debug exa", "exa 429", "exa 401".
allowed-tools	Read, Grep, Bash(curl:*), Bash(node:*)
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>
compatible-with	claude-code, codex, openclaw
tags	["saas","exa","debugging","errors"]

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 [e-mail].

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