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 a specific URL could not be processed
Solution: Verify the URL is valid and accessible, then retry
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: 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_DENIED403Feature requires a specific flag or permission you don’t have
FEATURE_DISABLED403Feature is disabled for your plan type
ROBOTS_FILTER_FAILED403All requested URLs were blocked by robots.txt
PROHIBITED_CONTENT403Request blocked by content safety moderation
CONTENT_FILTER_ERROR403Content 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_RESULTS400numResults 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_RESPONSE501Unable 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 (or /search with contents options), 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. 
{
  "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_TIMEOUT408Request timed out while fetching contentRetry the request or increase timeout if available
CRAWL_LIVECRAWL_TIMEOUT408Live crawl operation timed outTry again with livecrawl: "fallback" or 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: