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
403 - ForbiddenCause: Valid API key but insufficient permissions or rate limit exceeded
Solution: Check feature access permissions or implement rate limiting
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
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
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 and error message: 
{
  "requestId": "67207943fab9832d162b5317f4cca830",
  "error": "Invalid request body | Validation error: Invalid enum value. Expected 'never' | 'always' | 'fallback' | 'auto' | 'preferred' | 'fallback1.6', received 'alwayss' at \"livecrawl\""
}
Include the requestId when contacting support for faster troubleshooting.
When using the /contents endpoint, specific errors are returned in the statuses field rather than 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
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: