10. Errors

Repository: bloque-app/aledgent
Commit: 5ca6b8a
Version: 0.4.27
Status: draft
Rendered: 2026-10-17T19:30:18Z
Source: SPEC.md, last changed in 5ca6b8a

ID	Condition
`ERR-NotAuthorised`	The initiating principal holds no authority that covers this operation, account, asset or bound
`ERR-AuthorityRevoked`	The authority relied on has been revoked
`ERR-CredentialInvalid`	The credential presented is invalid, expired, or of the wrong kind
`ERR-RecoveryNotElapsed`	A recovery or succession was completed before its delay elapsed (`REQ-AU-16`)
`ERR-UnboundedGrant`	An authority grant was submitted without a bound (`REQ-AU-2`)
`ERR-BoundExceeded`	The operation would exceed a bound on the authority used
`ERR-UnknownAccount`	No such ledger account exists, or this principal cannot reach it
`ERR-AccountFrozen`	The account is frozen
`ERR-AccountClosed`	The account is closed
`ERR-AccountNotEmpty`	Closure attempted with a non-zero balance (`REQ-LA-4`)
`ERR-IdentityRestricted`	The owning identity is not allowed to transact
`ERR-UnknownAsset`	The asset is not in the registry (`REQ-AS-1`)
`ERR-AssetDeprecated`	The asset is registered but no longer accepts new operations
`ERR-PrecisionExceeded`	The amount has more precision than the asset (`REQ-AS-4`)
`ERR-ZeroAmount`	A zero amount was submitted where a movement was intended
`ERR-InsufficientAvailable`	The available balance does not cover the operation (`INV-3`)
`ERR-AmountMismatch`	A capture, or an observed external execution, differs from the reservation it belongs to (`INV-14`)
`ERR-ReleaseUnsafe`	A release was attempted while the external leg could still execute (`REQ-OP-9`)
`ERR-OperationTerminal`	The operation has already reached a terminal state (`INV-21`)
`ERR-InvalidTransition`	The requested state transition is not permitted (§5.6)
`ERR-UnknownOperation`	No operation with this reference
`ERR-DeadlineRequired`	A non-terminal operation was submitted without a deadline (`INV-15`)
`ERR-ClientKeyReused`	The same client key was submitted with a different request (`REQ-OP-10`)
`ERR-BatchTooLarge`	A multi-leg submission is larger than the declared maximum
`ERR-UnsupportedLeg`	The settlement adapter does not support this operation or asset (`REQ-SA-1`)
`ERR-SettlementLayerUnavailable`	The settlement adapter cannot be reached, or refuses to serve (`REQ-SA-2`)
`ERR-DecisionUnavailable`	The command cannot be decided now. Only a command answered with its decision gets it (`REQ-CS-8`). The command is kept; retrying with the same client key is safe and returns its decision (`REQ-CS-7`)
`ERR-ObservationDuplicate`	An observation with this coordinate has already been applied (`INV-12`)
`ERR-ObservationUnassociated`	An observation is valid but relates to no operation aledgent holds
`ERR-EvidenceInsufficient`	The evidence supplied does not establish the outcome claimed (`INV-11`)
`ERR-JustificationRequired`	An operator action was submitted without a justification
`ERR-ApprovalRequired`	A reversal, or a release without proof (`REQ-RC-5` step 3), was submitted without a second, distinct principal approving it (`REQ-OS-3`)
`ERR-DisclosureUnsupported`	aledgent cannot make the assertion requested
`ERR-DisclosureFalse`	aledgent can determine locally that the assertion is false (`REQ-DS-4`)
`ERR-NotDisclosable`	The subject has not authorised this disclosure, and no legal obligation applies
`ERR-AnchorNotFinal`	An anchor was cited whose publication has not reached finality (`REQ-PR-8`)
`ERR-QueryUnbounded`	A query was submitted without bounds that aledgent can serve (`REQ-CS-5`)
`ERR-MalformedCommand`	The request does not have a shape aledgent accepts: a field unknown or of the wrong type, a field a command requires and lacks, a value that does not parse, or a body over its bound (`REQ-ER-3`)
`ERR-InitialStateNotSealed`	The initial state committed at the book’s genesis is not yet in place and checked, and the book takes no command until it is sealed (`REQ-RC-6`)
`ERR-IdentifierArchived`	The identifier is one a prior system issued that the book’s initial state deliberately left out: it names no ledger account and never will (`REQ-RC-7`)
`ERR-Internal`	An unexpected fault inside aledgent. No detail is returned to the caller, and an incident is raised (`REQ-ER-2`)

REQ-ER-1 This list is closed. A condition not named here MUST NOT be returned. A condition MUST NOT be conveyed as a successful response carrying an error. The runtime shape of every error MUST be verified against its published description by a test. The test fails the build if they disagree.

REQ-ER-2 A fault inside aledgent, including a fault of the accounting core or of its binding, MUST be returned as ERR-Internal, with no detail, and MUST raise an incident. It MUST NOT be returned as a condition about the caller, such as ERR-NotAuthorised or ERR-InsufficientAvailable.

REQ-ER-3 A command whose shape aledgent does not accept MUST be refused with ERR-MalformedCommand, and nothing is taken in. That covers every shape fault of a command, on the command surface, the operator surface and the settlement adapter’s submissions: a field unknown or missing, a field of the wrong type, a body that is not the JSON the command takes, an identifier, encoding or enumerated value that does not parse, a list that must not be empty and is, a header that does not parse, a client key outside its bounds, pass-through data over its bound (REQ-PO-5), and a body over the bound the deployment takes for that command. Two things are not shape faults, and keep their own conditions:

A value that parses but is not acceptable. Excess precision is ERR-PrecisionExceeded, a reference to an account or operation aledgent does not hold is ERR-UnknownAccount or ERR-UnknownOperation, and a multi-leg submission over the published maximum is ERR-BatchTooLarge (REQ-CS-10).
A proof of possession that does not verify, or does not decode, is ERR-CredentialInvalid. So is anything sent to the routes that authenticate by what their body carries: they deny by default (NFR-7).

A read’s shape is held to the same rule. A read, on the query surface or the operator surface, whose shape aledgent does not accept MUST be refused with ERR-MalformedCommand, and nothing is read. A shape fault is found before anything is read, as it is for a command. It is: a parameter the route does not know, or one that is repeated; a value that does not parse into the type of its parameter, where any value made of digits is a count; an enumerated value outside its set; an account, identity or operation identifier, in a parameter or in the path, that does not parse; an asset symbol that is not 2 to 12 ASCII letters and digits; an alias source that cannot be one; and a cursor that is not hex. A parameter that is missing, or bounds that conflict, are not shape faults. They keep ERR-QueryUnbounded (REQ-CS-5): no subject, or two; no page size, or one outside 1 to 1000, however large; half a time range, or one reversed; a cursor issued for other filters; a statement without its account, asset, from or to; a statement period over its bound; an as_of the book has not reached. A value that parses but names nothing the caller may read keeps the condition for that (ERR-UnknownAccount, ERR-UnknownAsset, ERR-UnknownOperation, ERR-NotAuthorised). One read keeps a condition of its own: a disclosure to verify that is missing, or is not hex, is ERR-DisclosureUnsupported, because aledgent cannot make the assertion. This paragraph is about reads. It changes nothing for commands. Ruled by the owner on 2026-10-17 (amendment 0032).

A shape refusal names no field and quotes nothing the caller sent (REQ-AU-8).