API ReferenceWebhooks
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
Response200
{
"eventId": "evt_extfail_789",
"eventType": "DOCUMENT_EXTRACTION_FAILED",
"timestamp": "2024-01-15T10:32:15Z",
"organizationId": "org_xyz789",
"projectId": "proj_abc123",
"deploymentId": "dep_123abc",
"viaDeploymentId": "dpl_prod01",
"deploymentName": "production",
"schemaVersionId": "sv_7",
"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 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 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)
}