How Can Protocols Handle Partial Failure?
From the earlier reference collection. Read the current software blog.
A partial-failure contract identifies what succeeded, what failed, and which recovery actions are safe when an operation has multiple effects.
Make partial success visible
An operation that touches several resources may not finish as a single all-or-nothing action. A bulk request might update three records successfully and fail on a fourth. If the response only says “request failed,” the client cannot tell whether it should repair one item, repeat the whole request, or stop to inspect state.
Define the unit of success and failure. A response might report an overall status plus a result for each item, including a stable identifier, outcome, and error code where relevant. If the operation is atomic, state that all changes either commit or are rolled back. Do not leave clients to infer atomicity from an example.
Describe what remains true
For each failure mode, explain whether earlier effects remain committed. In a batch of records, the protocol could guarantee per-item commits: valid entries succeed independently, while invalid ones fail. Another design could validate the full batch before applying any change. Those approaches require different recovery behavior, so the contract must state which one applies.
For example, if a request updates five settings and the fourth has an invalid value, a per-item response should identify the other four outcomes. The client can then correct and resubmit only the failed setting. If the system instead rolls back the batch, the response should make clear that none of the five changes took effect.
Make recovery safe under uncertainty
A connection may fail after some effects occurred but before the client received the result. The protocol should explain how to learn the outcome, such as querying operation status with a request identifier. Where clients may retry, define idempotency or duplicate detection so a repeated request does not apply a successful effect twice.
Also describe dependencies between sub-operations. If creating a parent record succeeds but adding a child fails, a client needs to know whether the parent remains, whether it can be reused, and how to resume. A recovery procedure should reference the operation’s actual state rather than assume every retry starts from zero.
Design responses for repair
A useful partial-failure response is specific enough to support a next action: identify the affected unit, state its outcome, explain the reason, and provide a safe recovery path. Avoid exposing internal details that do not help the caller. Include examples for full success, mixed results, and an uncertain outcome after interruption.
The goal is not to make every operation complicated. It is to make multi-part behavior honest. When a protocol names what committed and what did not, clients can recover precisely, operators can diagnose issues, and repeated work is less likely to create inconsistent state.