Skip to main content
When data is late or missing, someone downstream feels it. Kadoa prevents that by classifying every failure, telling you whose fault it is, notifying you through the channel you choose, and recovering automatically from most errors. When something breaks and gets fixed, you’ll know what happened, why, and how it was resolved.

​
Understanding Runs vs Workflows

  • Run: A single execution of your workflow at a scheduled time
  • Workflow: The configuration that schedules and manages runs
When errors occur, they affect individual runs - your workflow schedule continues regardless.

​
Error Handling

Every failed run tells you whether the issue is with the website, with Kadoa, or with the data itself. Kadoa uses a multi-layer approach to handle issues automatically:

​
1. Self-Healing (Automatic)

Our AI adapts to changes without intervention:
  • Detects page structure changes and updates selectors
  • Adjusts to new layouts and UI elements
  • Retries with different strategies when extraction fails
  • Agent investigates any issues automatically
Most issues are resolved at this stage without you knowing.

​
2. Error Detection & Recovery

If self-healing can’t resolve the issue:
  • System enters error state
  • Automatic retries with expanded strategies
  • You’re notified via email and dashboard

​
3. Support Investigation

For complex issues that can’t auto-recover:
  • Kadoa support team is automatically alerted
  • Engineers investigate with detailed error logs
  • Manual fixes are applied when needed
Common issues we handle: authentication problems, site maintenance, anti-bot challenges, and network failures. Most failures resolve without your involvement. Kadoa detects site changes and adapts scrapers automatically.

​
Error Format

Errors are returned per run in the history endpoint: 
{
  "errors": [{
    "errorCode": "BLOCKED_ACCESS",
    "message": "Access blocked by website security",
    "timestamp": "2025-01-15T10:30:00Z",
    "screenshot": "https://storage.googleapis.com/...",
    "context": {
      "url": "https://example.com/page",
      "httpStatus": 403,
      "retryCount": 3
    }
  }]
}
Each error includes a screenshot of what the scraper saw, so you can verify the cause yourself.

​
What Happens When Errors Occur

​
For website and Kadoa issues:

  1. Run marked as FAILED - visible in the dashboard and API
  2. You’re notified - if you’ve subscribed to workflow_failed events (see below)
  3. Kadoa retries automatically - self-healing technology attempts recovery on the next run
  4. Ops team is notified - critical errors are flagged for investigation
  5. Submit a support request - use the Support Center for expedited help
Screenshot

​
For data issues:

  • Run completes normally, no intervention needed
  • Previous data remains unchanged
  • Review extracted data for completeness

​
Get Notified About Failures

Don’t poll the dashboard. Set up notifications so failures come to you. Subscribe to Workflow health events (workflow_failed) via the dashboard or API. This covers both failures and recoveries. Choose your channel:
ChannelBest for
EmailDaily review, non-urgent updates
SlackReal-time team awareness
WebhookFeeding into internal alerting (PagerDuty, Datadog, etc.)
You can also subscribe to workflow_finished and workflow_data_change events. See Notifications for the full setup guide.

​
Track Run History

Every workflow keeps a full history of runs. Use it to spot patterns like intermittent blocks, declining record counts, or degraded performance. 
GET /v4/workflows/{workflowId}/history
Each run includes:
  • Status: FINISHED, FAILED, IN_PROGRESS, VALIDATING
  • Timestamps: startedAt, finishedAt
  • Records extracted: row count
  • Screenshot: what the page looked like during extraction
  • Errors: full error details with context