Business incidents

Read this when the transactional tutorial reaches validation failures or .WithBusinessIncidents(...).

A business incident is a tracked event for a failure the platform cannot fix by retrying. A missing customer, invalid VAT number, or blocked receiving system needs a process owner, not another attempt from the runtime.

Technical failure or business incident

Case	Classification	Result
Socket reset, timeout, database unavailable	Technical failure	Retry, then dead-letter if it keeps failing.
Message violates a business rule	Business incident	Skip this message and notify the owner.
Destination rejects data that a person must correct	Business incident	Skip this message and notify the owner.

The split keeps operational noise out of the technical channel. Technical failures should mean the integration or platform needs attention.

What your step returns

A business step returns incident data as a value:

return new BusinessStepResult<In>.Failure(new BusinessIncidentData(
    Description: "Order has no lines",
    Context: new Dictionary<string, string> { ["orderId"] = input.OrderId }));

The step states the rule and the useful context. It does not send the incident itself.

What routing adds

The pipeline wiring adds identity when .WithBusinessIncidents(...) is configured:

Field	Purpose
source	Component that raised the incident.
subject	Business identifier a person recognises.
id	Stable message id used to update the same incident across retries.

If the same message fails again, the existing incident is updated rather than duplicated. If a retry later succeeds, the incident can be resolved automatically.

Use Route business incidents when you need the wiring checklist.