Expand description
Structured error codes (SPEC.md §Errors, issue #9).
Before this module the wire error was a bare string. A host receiving one could log it and nothing else: it could not distinguish “your query was malformed” (do not retry) from “I am overloaded” (retry with backoff) from “I do not serve that frame kind” (stop asking) from “internal fault” (fail over). Every SDK and host would have invented its own message-string sniffing — exactly the convention-over-contract the protocol exists to eliminate.
ErrorCode is a small, open vocabulary carried alongside the
free-form message, never replacing it: the code is for the machine, the
message is for the human reading the log.
§Forward compatibility
The vocabulary is open. An unrecognised code round-trips losslessly as
ErrorCode::Unknown and MUST be reacted to as though it were
ErrorCode::Internal — the conservative choice, since a host that guessed
optimistically about an error it does not understand would retry things it
should not. This is what lets the vocabulary grow in a 1.x minor without
breaking deployed hosts.
Enums§
- Error
Code - A machine-readable provider error code.
- Host
Reaction - What a host should do about a provider error. Advisory guidance attached to
each
ErrorCode, so the reaction lives with the vocabulary rather than being re-derived by every host.