A failed read answers a fixed message and reports the real one
The category door was the counter-example: it returned whatever the storage layer said and logged nothing, so a class name or a failed query was published to any caller who could read the list.
The rule
Normative: this is the rule
- Where a read fails, the response body carries a fixed message naming what failed and nothing more; the underlying error is reported through the implementation's own error channel, never published to the caller.
- This binds cacheable responses exactly as it binds every other kind: an error shape is not exempt because it is served from a different response path.
What it means
A failed read does not forward whatever the underlying failure said: the caller gets one fixed message naming what failed, and the real detail goes only to the implementation's own error channel. This holds even on a door whose successful response is cacheable — a cacheable response path is not an exemption from the rule, so an error answer must not slip through it unfiltered.
Example
A storage failure that would otherwise say exactly what broke:
GET /api/flowdrop/categories
{"success": false, "error": "Failed to fetch categories"}Nothing about the storage failure itself — its own raised message — reaches that body.
Rule identifiers are permanent and are never renumbered. Each implementation publishes its own standing against these rules; this specification does not.spec 1.0-draft · META-3 · changed in spec 1.0