Understanding failures

The Maintenance Agent evaluates more than the raw error message. Depending on the failure, it can use the error screenshot, visible page state, DOM and selector signals, current URL, failing step, recent actions, context from successful runs, and patterns from previous failed runs. It also learns from recovery outcomes and can apply site-specific knowledge about recurring timing, selector, popup, validation, login, and outage behavior. The resulting category, sub-type, and explanation are available in the Retrieve Run Results response as llm_error_category, llm_error_sub_type, and llm_error_description. Terminal failures also include them in the execution.failed webhook.

Error-classification matrix

Category	Sub-types	Customer meaning
`SERVICE_UNAVAILABLE`	`APPLICATION_ERROR`, `SERVICE_RETIRED`, `MAINTENANCE_DOWNTIME`, `SILENT_ERROR`	The external application errored, is under maintenance, was retired, or is silently broken
`AUTHENTICATION_ERROR`	`INVALID_CREDENTIALS`, `MFA_CODE_REJECTED`, `ACCESS_DENIED`, `TOO_MANY_ATTEMPTS`, `ACCOUNT_LOCKED`	Login, verification, credentials, or account access failed
`PAGE_STILL_LOADING`	`IN_PROGRESS`, `PREMATURE_ACTION`	The page had not finished loading, or the action fired before its target was ready
`UNEXPECTED_UI_STATE`	`ACTION_REQUIRED`, `DECISION_REQUIRED`	A popup, dialog, overlay, or banner blocked progress — dismissible, or needing a consequential decision
`PASSWORD_UPDATE_REQUIRED`	`DISMISSIBLE`, `NON_DISMISSIBLE`	The site presented an optional or mandatory password-change screen
`INCORRECT_INPUTS`	`FIELD_VALIDATION_ERROR`, `NO_MATCHING_OPTION`, `MULTIPLE_MATCHING_RESULTS_FOUND`	An input was rejected by validation, had no matching option, or matched several ambiguous results
`XPATH_INCORRECT`	—	A selector found no element, multiple elements, or the wrong element

Getting Started

Concepts

API Reference

SDK

Integrations

Understanding failures

Error-classification matrix