Document Extraction Failed Event
Webhook event fired when document extraction fails due to errors or timeouts.
The DOCUMENT_EXTRACTION_FAILED event fires when document extraction does not complete successfully. Subscribe to it when you need to react to failures separately from successful extractions.
When It Triggers
- Extraction error -- When document processing fails due to an unrecoverable error
- Timeout -- When processing exceeds the allowed time and is abandoned
This is a document event, routed to subscriptions by deployment route. It typically fires within 30-120 seconds after calling the process-file or process-file-async endpoint.
Payload Structure
{
"eventId": "evt_extfail_789",
"eventType": "DOCUMENT_EXTRACTION_FAILED",
"timestamp": "2024-01-15T10:32:15Z",
"organizationId": "org_xyz789",
"projectId": "proj_abc123",
"deploymentId": "dep_123abc",
"extractionSchemaId": "schema_456def",
"fileId": "file_bad123",
"jobId": "job_error456",
"data": {
"status": "failed",
"errorMessage": "Document format not supported"
}
}Payload Fields
| Field | Type | Description |
|---|---|---|
eventId | string | Unique event identifier. Use for idempotency. |
eventType | string | Always "DOCUMENT_EXTRACTION_FAILED" |
timestamp | ISO 8601 | When the extraction failed (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 processed file identifier |
jobId | string | null | The extraction job identifier, if available |
data.status | "failed" | Always "failed" for this event |
data.errorMessage | string | null | Error description |
Handling the Event
function handleDocumentExtractionFailed(event) {
const { eventId, fileId, jobId, data } = event
console.error(`Document ${fileId} extraction failed (job: ${jobId}): ${data.errorMessage}`)
notifyOnCall(fileId, data.errorMessage)
scheduleReprocess(fileId)
}Notes
Before PRD 0140 this event was defined but never delivered; extraction failures surfaced through the DOCUMENT_EXTRACTED event with data.status: "failed". It is now delivered as its own event type. If you previously relied on DOCUMENT_EXTRACTED to observe failures, subscribe to DOCUMENT_EXTRACTION_FAILED as well.