Document Validation Failed Event

The DOCUMENT_VALIDATION_FAILED event fires when a validation attempt cannot complete -- the job was dropped, the validator agent run died, or the attempt was abandoned. It closes the hole where a document that was never validated simply stayed silent.

This event reports that validation did not run to a verdict. It is not a failing validation result: a validation that ran and found problems settles normally and reports through DOCUMENT_VALIDATED with status: "failed".

When It Triggers

`data.reason`	Meaning
`DLQ`	The static validation job exhausted its retries and landed in the dead-letter queue
`ABORTED`	The attempt could not be dispatched, or was abandoned before running
`AGENT_RUN_FAILED`	The validator agent run terminated without submitting a verdict
`TIMEOUT`	The attempt exceeded the validation watchdog's hard cap
`NOT_DISPATCHED`	Validation was expected for the document but no attempt was ever dispatched

This is a document event, routed to subscriptions by deployment route.

Payload Structure

Response200

{
  "eventId": "evt_valfail_202",
  "eventType": "DOCUMENT_VALIDATION_FAILED",
  "timestamp": "2024-01-15T10:52:00Z",
  "organizationId": "org_xyz789",
  "projectId": "proj_abc123",
  "deploymentId": "dep_123abc",
  "extractionSchemaId": "schema_456def",
  "fileId": "file_789ghi",
  "data": {
    "reason": "AGENT_RUN_FAILED",
    "errorMessage": "Validation agent run failed",
    "source": "AGENT",
    "validationAttemptId": "cm5attempt001"
  }
}

Payload Fields

Field	Type	Description
`eventId`	string	Unique event identifier. Use for idempotency.
`eventType`	string	Always `"DOCUMENT_VALIDATION_FAILED"`
`timestamp`	ISO 8601	When the attempt was written off (UTC)
`organizationId`	string	Your organization identifier
`projectId`	string	The project the document belongs to
`deploymentId`	string	The model or deployment that processed this document
`extractionSchemaId`	string	The extraction schema ID of that model or deployment
`fileId`	string	The document whose validation failed
`data.reason`	string	One of the reasons in the table above
`data.errorMessage`	string	Human-readable detail, truncated
`data.source`	`"STATIC"` \| `"AGENT"`	Which validation path failed
`data.validationAttemptId`	string \| null	Correlates with the attempt's other events. `null` for attempts started before attempt ids existed.

A Later Verdict Supersedes This Event

A validation that submits late -- an agent that recovers after its run was written off, for example -- still settles the document and emits DOCUMENT_VALIDATED. The event with the later timestamp wins: a DOCUMENT_VALIDATED supersedes an earlier DOCUMENT_VALIDATION_FAILED for the same document.

Delivery is queued, retried and processed concurrently, so receipt order is not state order. Compare timestamp per fileId before overwriting stored state, or re-read the document rather than applying an event blind. Note that this event is attempt-scoped while DOCUMENT_VALIDATED is document-scoped, so the two do not always carry the same validationAttemptId.

Handling the Event

function handleValidationFailed(event) {
const { fileId, data } = event

console.warn(`Validation for ${fileId} did not complete: ${data.reason} (${data.errorMessage})`)

if (data.reason === "AGENT_RUN_FAILED" || data.reason === "TIMEOUT") {
  routeToManualReview(fileId)
} else {
  scheduleRevalidation(fileId)
}
}