Document Validation Failed Event

The DOCUMENT_VALIDATION_FAILED event fires when validation cannot complete -- the job was dropped, the validator agent run died, the attempt was abandoned, or evaluating the model's validation rules broke. 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", and a rule that fails is reported there too.

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 -- also the reason when rule evaluation fails for a document whose model has rules
`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

A rule evaluation failure carries source: "STATIC" and validationAttemptId: null, because rules run synchronously and start no attempt. DOCUMENT_EXTRACTED is published first and this event follows it, so a read triggered by either already reports validation status error with an empty rule list. The document does not stay pending: it settles with status: "error" on DOCUMENT_VALIDATED once the custom lanes, if any, finish -- immediately when there are none.

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",
  "viaDeploymentId": "dpl_prod01",
  "deploymentName": "production",
  "schemaVersionId": "sv_7",
  "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 ID of the model that processed this document
`viaDeploymentId`	string \| null	The ID of the deployment the request arrived through. `null` when the request named the model directly
`deploymentName`	string \| null	The name of that deployment, such as `"production"`. `null` whenever `viaDeploymentId` is `null`
`schemaVersionId`	string \| null	The ID of the frozen schema version the run resolved to. `null` when the deployment tracks the draft schema
`extractionSchemaId`	string	The extraction schema ID of that model
`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. Rule evaluation reports `"STATIC"`
`data.validationAttemptId`	string \| null	Correlates with the attempt's other events. `null` for a rule evaluation failure, which has no attempt, and 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)
}
}