Status alone is not enough
HTTP status codes provide a useful first category, but two 409 responses can represent very different business conflicts. A structured error document can carry a stable code, request identifier and relevant context so callers know what kind of recovery is possible.
That is especially important in a policy-heavy product where denial can be an expected and correct outcome.
Request identifiers shorten support loops
When a customer reports a failed operation, a request identifier can connect the client-visible error to server-side diagnostics without asking them to reconstruct the exact second and payload from memory.
The identifier should be safe to share with support and useful across logs and audit where appropriate.
Errors are part of the contract
Validation failure, policy denial, hold conflict, regional conflict and expired share are not interchangeable. Documenting them helps client developers build deliberate behaviour instead of showing “something went wrong” for every case.
Clear failure semantics are a security feature because they make fail-closed behaviour visible and testable.
Operate the failure
A structured error should name the class of failure, the object identity and a stable code operators can search. That is what makes retries and support tickets tractable.