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 Attribution

Every failed run tells you whether the issue is with the website, with Kadoa, or with the data itself.

​
Website Issues

The target site is the problem. Kadoa retries automatically on the next scheduled run.
Error CodeWhat Happened
BLOCKED_ACCESSSite blocked the request (geo-blocking, bot detection, IP ban)
MAINTENANCESite is down or in maintenance mode
TECHNICAL_ERRORSite returned a server error (HTTP 500, 502, 503)

​
Kadoa Issues

Something went wrong on our side. Our ops team is notified immediately.
Error CodeWhat Happened
KADOA_INTERNAL_ERRORInternal processing error (rare)
NOT_SUPPORTEDSource structure is incompatible with current scraper
OUT_OF_FUNDSInsufficient credits in your account

​
Data Issues

The run completed, but the results may need your attention.
Error CodeWhat Happened
CONFIRMED_NO_DATAPage loaded correctly but contains no data matching your schema
PAGINATION_INCOMPLETESome pages were missed, but data was extracted from accessible pages
DATA_VALIDATION_ISSUES_THRESHOLD_REACHEDData quality fell below your configured threshold

​
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
  • Timestamps: startedAt, finishedAt
  • Records extracted: row count
  • Screenshot: what the page looked like during extraction
  • Errors: full error details with context

​
Automatic Recovery

Most failures resolve without your involvement. Kadoa detects site changes and adapts scrapers automatically. For real-time monitors, health is checked continuously: Running → Degraded (15 min without data) → Failed (30 min) Recovery is automatic once the underlying issue resolves. See workflow states for details. Have questions about monitoring your workflows? Contact the support team.