API ReferenceWebhooks
Document Classification Failed Event
Webhook event fired when document classification fails.
The DOCUMENT_CLASSIFICATION_FAILED event fires when a document cannot be classified. Subscribe to it to catch documents that never reach extraction because the classification step failed.
When It Triggers
- Classification error -- When the classifier fails to route a document to a deployment
- Unrecognized document -- When a document cannot be matched to a known type
This is a document event, routed to subscriptions by deployment route.
Payload Structure
Response200
{
"eventId": "evt_classfail_321",
"eventType": "DOCUMENT_CLASSIFICATION_FAILED",
"timestamp": "2024-01-15T10:31:05Z",
"organizationId": "org_xyz789",
"projectId": "proj_abc123",
"deploymentId": "dep_123abc",
"extractionSchemaId": "schema_456def",
"fileId": "file_bad123",
"jobId": null,
"data": {
"status": "failed",
"errorMessage": "Could not classify document"
}
}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 document belongs to |
deploymentId | string | The deployment associated with this document |
extractionSchemaId | string | The extraction schema associated with this document |
fileId | string | The processed file identifier |
jobId | string | null | The job identifier, if available |
data.status | "failed" | Always "failed" for this event |
data.errorMessage | string | null | Error description |
Handling the Event
function handleDocumentClassificationFailed(event) {
const { eventId, fileId, data } = event
console.error(`Document ${fileId} classification failed: ${data.errorMessage}`)
routeToManualTriage(fileId)
}Notes
Before PRD 0140 this event was defined but never delivered. It is now delivered as its own event type, distinct from DOCUMENT_EXTRACTED. Subscribe to it if you need to catch classification failures independently.