Skip to main content

​
API errors

CodeOverview
400 - Bad RequestCause: Invalid request parameters, malformed JSON, missing required fields
Solution: Check request body format, validate parameters, ensure API key is correctly formatted
401 - UnauthorizedCause: Missing or invalid API key
Solution: Verify your API key is correct and active, ensure proper authentication headers
402 - Payment RequiredCause: Account credits exhausted or API key spending budget exceeded
Solution: Top up credits at dashboard.exa.ai or contact your team administrator to increase the API key budget
403 - ForbiddenCause: Valid API key but insufficient permissions, feature disabled for your plan, or content blocked by policy
Solution: Check feature access permissions for your plan, verify the content is not blocked by robots.txt or content moderation
404 - Not FoundCause: Resource not found (e.g., Webset, task, or URL doesn’t exist)
Solution: Verify the resource identifier exists and is accessible
409 - ConflictCause: Resource already exists (e.g., Webset with same externalId)
Solution: Use a different identifier or update the existing resource
422 - Unprocessable EntityCause: Request was well-formed but could not be processed — e.g., a URL that failed to fetch (/contents), or a query that could not be decomposed into a valid entity/criteria pair (/websets)
Solution: Check the error message for details; verify URLs are accessible or rephrase your query
429 - Too Many RequestsCause: Rate limit exceeded
Solution: Implement exponential backoff and reduce request rate
500 - Internal Server ErrorCause: Issue on our servers
Solution: Retry your request after a brief wait and contact us if the issue persists
501 - Not ImplementedCause: /answer and /research only — the model was unable to generate a response for the given query with the available information
Solution: Try rephrasing your query or adjusting parameters
502 - Bad GatewayCause: Upstream server issue
Solution: Retry the request after a brief delay
503 - Service UnavailableCause: Service temporarily down
Solution: Retry after delay, check for maintenance announcements

​
Error Response Structure

All error responses include a requestId field, error message, and an error tag: 
{
  "requestId": "67207943fab9832d162b5317f4cca830",
  "error": "Invalid request body | Validation error: Invalid enum value. Expected 'never' | 'always' | 'fallback' | 'auto' | 'preferred' | 'fallback1.6', received 'alwayss' at \"livecrawl\"",
  "tag": "INVALID_REQUEST_BODY"
}
Include the requestId when contacting support for faster troubleshooting. The tag field identifies the specific error type programmatically.
Rate limit errors (429) use a simpler response format with only an error field: 
{
  "error": "You've exceeded your Exa rate limit of 10 requests per second. If you want this increased, please email hello@exa.ai :)"
}

​
API Error Tags

Error tags provide programmatic identification of the specific error. Use the tag field in the response to handle errors in your code.

​
Authentication & Authorization

TagHTTP CodeDescription
INVALID_API_KEY401API key is missing, empty, or invalid
NO_MORE_CREDITS402Account credits are exhausted — top up at dashboard.exa.ai
API_KEY_BUDGET_EXCEEDED402API key has exceeded its spending budget — contact your team administrator
ACCESS_DENIED403/search only — feature requires a specific flag or permission you don’t have
FEATURE_DISABLED403Feature is disabled for your plan type
ROBOTS_FILTER_FAILED403/contents only — all requested URLs were blocked by robots.txt
PROHIBITED_CONTENT403/answer and /research only — request blocked by content safety moderation
CONTENT_FILTER_ERROR403/search only — content was filtered due to safety policy

​
Request Validation

TagHTTP CodeDescription
INVALID_REQUEST_BODY400Request body failed validation (malformed JSON, missing fields, invalid parameter values)
INVALID_REQUEST400Conflicting parameters (e.g., setting both livecrawl and maxAgeHours)
INVALID_URLS400One or more URLs/IDs are in an invalid format
INVALID_NUM_RESULTS400/search only — numResults must be ≤ 100 when using highlights
INVALID_FLAGS400Unrecognized flags in request
INVALID_JSON_SCHEMA400Provided JSON schema is invalid (used by /answer)
NUM_RESULTS_EXCEEDED400Requested number of results exceeds your plan’s limit
NO_CONTENT_FOUND400No contents could be found for the given URLs

​
Processing Errors

TagHTTP CodeDescription
FETCH_DOCUMENT_ERROR422A specific URL could not be processed
UNABLE_TO_GENERATE_RESPONSE501/answer and /research only — unable to generate a response with the available information
DEFAULT_ERROR500Unexpected server error — retry after a brief wait
INTERNAL_ERROR500Unclassified internal error — retry after a brief wait

​
Content Fetch Status Tags

When using the /contents endpoint, per-URL errors are returned in the statuses field rather than as HTTP error codes. This allows for granular error handling when fetching multiple URLs. These status tags are specific to the /contents endpoint and are not returned by /search. 
{
  "results": [...],
  "statuses": [
    {
      "id": "https://example.com",
      "status": "error",
      "error": {
        "tag": "CRAWL_NOT_FOUND",
        "httpStatusCode": 404
      }
    }
  ]
}
TagHTTP CodeDescriptionHow to Handle
CRAWL_NOT_FOUND404Content not found at the specified URLVerify the URL is correct and accessible
CRAWL_TIMEOUT504The crawl timed out while fetching content from the target pageRetry the request or try again later
CRAWL_LIVECRAWL_TIMEOUT504Content could not be retrieved within your requested livecrawlTimeoutIncrease livecrawlTimeout, use livecrawl: "fallback", or use livecrawl: "never"
SOURCE_NOT_AVAILABLE403Access forbidden or source unavailableCheck if the source requires authentication or is behind a paywall
UNSUPPORTED_URL—URL scheme is not supported for content fetchingUse a standard HTTP/HTTPS URL
CRAWL_UNKNOWN_ERROR500+Other crawling errorsRetry the request; contact support if persistent

​
Getting Help

If you encounter persistent errors or need clarification on error codes: