Document Classification Failed Event

The DOCUMENT_CLASSIFICATION_FAILED event fires when a classification run breaks before it can reach a decision. Subscribe to it to catch documents that never made it to a verdict at all.

This is not the "document did not route" event. A document the classifier looked at and declined to route is a normal outcome, and it arrives on DOCUMENT_CLASSIFIED with data.status of "unclassified". This event means the run itself failed.

When It Triggers

Missing or unreadable file -- the file could not be fetched or converted
Inference error -- the model call failed or returned something unusable
Pipeline error -- the classifier had no usable routes, or the run threw

Routing

This is a classifier event, routed to subscriptions by classifier route.

Before this release the event was defined but routed by deployment -- and a run that fails has not routed anywhere, so it had no deployment to key off and was never delivered. It is now keyed on the classifier, which is known from the moment the run starts.

The payload changed with that fix: deploymentId, extractionSchemaId and jobId are gone; classifierId and classificationId are new. No subscription in production selected this event, so no delivered payload changed shape.

Payload Structure

Response200

{
  "eventId": "evt_classfail_321",
  "eventType": "DOCUMENT_CLASSIFICATION_FAILED",
  "timestamp": "2024-01-15T10:31:05Z",
  "organizationId": "org_xyz789",
  "projectId": "proj_abc123",
  "classifierId": "clf_123abc",
  "classificationId": "cls_456def",
  "fileId": "file_bad123",
  "data": {
    "status": "failed",
    "errorMessage": "No object generated: response did not match schema"
  }
}

Payload Fields

Field	Type	Description
`eventId`	string	Unique event identifier. Use for idempotency.
`eventType`	string	Always `"DOCUMENT_CLASSIFICATION_FAILED"`
`timestamp`	ISO 8601	When the classification failed (UTC)
`organizationId`	string	Your organization identifier
`projectId`	string	The project the classifier belongs to. See the note below for global classifiers.
`classifierId`	string	The classifier whose run failed
`classificationId`	string	The classification run that failed
`fileId`	string	The file that could not be classified
`data.status`	`"failed"`	Always `"failed"` for this event
`data.errorMessage`	string \| null	Error description

projectId for a global classifier

A global classifier is shared across every project in your organization, and a failed run never routed anywhere, so there is no single project the event belongs to. Each subscription therefore receives its own projectId — the project the webhook is configured in. classifierId, classificationId and fileId are the same for every subscriber and are the safest keys for your own bookkeeping.

Handling the Event

function handleDocumentClassificationFailed(event) {
const { fileId, classifierId, data } = event

console.error(`Classifier ${classifierId} failed on ${fileId}: ${data.errorMessage}`)

routeToManualTriage(fileId)
}

Notes

Unlike an unclassified outcome, a failure is worth retrying -- the run broke, it did not decide.