Document Split Failed Event

The DOCUMENT_SPLIT_FAILED event fires when a split run cannot complete. The source document stays where it is and no segment files are created.

When It Triggers

Run error -- the splitter could not read or process the source document
Timeout -- the run exceeded its time budget
Retries exhausted -- the queued job failed its final attempt

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

Payload Structure

Response200

{
  "eventId": "evt_split_failed_301",
  "eventType": "DOCUMENT_SPLIT_FAILED",
  "timestamp": "2024-01-15T10:36:40Z",
  "organizationId": "org_xyz789",
  "projectId": "proj_abc123",
  "splitterId": "spl_123abc",
  "splitId": "split_456def",
  "fileId": "file_789ghi",
  "data": {
    "status": "failed",
    "errorMessage": "Source document could not be converted to PDF"
  }
}

Payload Fields

Field	Type	Description
`eventId`	string	Unique event identifier. Use for idempotency.
`eventType`	string	Always `"DOCUMENT_SPLIT_FAILED"`
`timestamp`	ISO 8601	When the split failed (UTC)
`organizationId`	string	Your organization identifier
`projectId`	string	The project the splitter belongs to
`splitterId`	string	The splitter that ran
`splitId`	string	This split run
`fileId`	string	The source file that could not be split
`data.status`	`"failed"`	Always `"failed"` for this event
`data.errorMessage`	string \| null	Error description

Handling the Event

function handleDocumentSplitFailed(event) {
const { fileId, splitId, data } = event

console.error(`Split ${splitId} of ${fileId} failed: ${data.errorMessage}`)

routeToManualTriage(fileId)
}

Notes

A failed split may be retried automatically before this event fires. When it does fire, the run is terminal -- retrying is your call.