docs: rewrite reference prose and correct field code citations (#2592)

fluxer_docs/src/content/docs/http-api/errors.md

@@ -12,7 +12,7 @@ The `message` field is rendered from a template, is translated per request, and
 
 ## Selecting the error code
 
-An error response always has `code` and `message`. A failure with more to report adds its own members beside those two. Every added member sits at the top level of the response. A rate limit denial adds `global` and `retry_after`, a missing scope adds `required_scope`, and a validation failure adds `errors`.
+An error response always has `code` and `message`. A failure with more to report adds its own members beside those two, at the top level of the response. A rate limit denial adds `global` and `retry_after`, a missing scope adds `required_scope`, and a validation failure adds `errors`.
 
 :::note[OAuth2 endpoints use a different envelope]
 An OAuth2 protocol failure raised by the [OAuth2 resource](/http-api/oauth2/) answers with the RFC 6749 shape. That body is `error` and `error_description` and nothing else, so its values appear in no registry here.
@@ -22,7 +22,13 @@ An OAuth2 protocol failure raised by the [OAuth2 resource](/http-api/oauth2/) an
 
 The error code determines which supplementary members a failure has, and most codes have none. A client reads only the members documented for the code it matched. `errors` is the list of field violations. `retry_after` is the delay before another attempt is admitted, `global` is `true` on a global rate limit denial and `false` on a route one, `required_scope` is the OAuth2 scope the request is missing, and `has_mfa` and `methods` are the [sudo mode](/http-api/users/mfa/#sudo-mode) proofs an account can supply.
 
-The two IP ban codes have their own members. `GLOBAL_IP_BANNED` and `GLOBAL_IP_TEMPORARILY_BANNED` both have `ip_address` with the normalised client address, `appeal_email` with the address an appeal is sent to, `appeals_supported` which is `true` only for the permanent ban, and `ban_kind` which is `permanent` or `temporary_24h`. `expires_at` is an ISO 8601 timestamp when the ban records an expiry and `null` otherwise, including on every permanent ban.
+`GLOBAL_IP_BANNED` and `GLOBAL_IP_TEMPORARILY_BANNED` have their own members:
+
+- `ip_address` is the normalised client address.
+- `appeal_email` is the address an appeal is sent to.
+- `appeals_supported` is `true` only for the permanent ban.
+- `ban_kind` is `permanent` or `temporary_24h`.
+- `expires_at` is an ISO 8601 timestamp when the ban records an expiry, and `null` otherwise, including on every permanent ban.
 
 ## Validation failure codes
 
@@ -56,7 +62,7 @@ The `path` of an element is the dot-joined position of the failed value, so a ne
 An empty or whitespace-only body becomes `{}`, so the response reports the fields the schema then finds missing. A body that does not parse as JSON returns 400 `INVALID_FORM_BODY` with one element at path `body` and code `INVALID_FORMAT`.
 :::
 
-Fluxer normalises empty values on all four targets before validation runs. An empty string becomes `null` wherever it appears, including inside an array element. A nested object becomes `null` when it holds no members, and it becomes `null` when every one of its members is `null` after Fluxer has applied the same rule to each of them. The top-level object itself is never replaced, so a request that sends nothing still reaches the schema as an object and fails on the fields the schema requires.
+Fluxer normalises empty values on all four targets before validation runs. An empty string becomes `null` wherever it appears, including inside an array element. A nested object becomes `null` when it holds no members. It also becomes `null` when every one of its members is `null` after Fluxer has applied the same rule to each of them. The top-level object itself is never replaced, so a request that sends nothing still reaches the schema as an object and fails on the fields the schema requires.
 
 :::caution[An enumerated validation failure answers 400 alone]
 A validation failure whose elements have enumerated codes answers 400 with its elements in `errors`, and its top-level code is `INVALID_FORM_BODY` everywhere except [Modify current user settings](/http-api/users/settings/#modify-current-user-settings). Any other status, retry guidance, or response header from the original failure is dropped.
@@ -79,9 +85,9 @@ A boundary schema constraint can name its own [validation code](#validation-erro
 
 ## HTTP status fallback codes
 
-A failure that has an HTTP status and no recognised Fluxer error code takes the fallback `code` its status selects below. An unclassified 401, 413, 422, or 429 falls back to `GENERAL_ERROR`. An error named by an operation or by one of the registries below keeps that more specific code.
+A failure that has an HTTP status and no recognised Fluxer error code takes the fallback `code` its status selects below. Where an operation or one of the registries below names the error, Fluxer keeps that more specific code. An unclassified 401, 413, 422, or 429 falls back to `GENERAL_ERROR`.
 
-An unrecognised failure returns 500 with `INTERNAL_SERVER_ERROR` and a generic message that names no detail. A failure that has a registered API code but no status returns 400, except `GENERAL_ERROR`, which returns 500.
+Fluxer answers an unrecognised failure with 500 `INTERNAL_SERVER_ERROR` and a generic message that names no detail. A failure that has a registered API code but no status returns 400, except `GENERAL_ERROR`, which returns 500.
 
 | Status | Code | Description |
 | --- | --- | --- |
@@ -118,14 +124,14 @@ The window length, both thresholds, and the number of windows the score trigger
 
 ## API error code registry
 
-These codes appear in the top-level `code` field of an error response, transmitted as the exact JSON string shown. The registry is closed and holds exactly 264 codes. Each entry states the leading sentence of the English source message, without its final full stop. Those messages call a [guild](/http-api/guilds/) a community.
+These codes appear in the top-level `code` field of an error response, transmitted as the exact JSON string shown. The registry is closed. Each entry states the leading sentence of the English source message, without its final full stop. Those messages call a [guild](/http-api/guilds/) a community.
 
 :::note[The rendered `message` fills in the braced values]
 A description containing a value in braces is an ICU MessageFormat template. `You've reached the maximum of {count, plural, one {# emoji} other {# emojis}}` renders as a complete sentence with the applicable limit.
 :::
 
 :::note[A rendered `message` can run longer than the registry entry]
-Several source messages append a further recovery sentence with a template value such as a maximum size, a format list, or a retry delay. A client branches on `code` and reads the members the operation documents.
+Several source messages append a further recovery sentence with a template value such as a maximum size, a format list, or a retry delay.
 :::
 
 ### `ACCESS_DENIED`
@@ -1187,7 +1193,7 @@ You've reached the maximum of {count, plural, one {# WebAuthn credential} other
 
 ## Validation error code registry
 
-These codes appear in the `code` field of an element in the top-level `errors` array on an `INVALID_FORM_BODY` response. Each names one specific input constraint. A schema failure whose constraint names no code of its own reports one of the [default schema failure codes](#default-schema-failure-codes). The registry is closed and holds exactly 236 codes. Each entry states the leading sentence of the English source message, the same way.
+These codes appear in the `code` field of an element in the top-level `errors` array on an `INVALID_FORM_BODY` response. Each names one specific input constraint. A schema failure whose constraint names no code of its own reports one of the [default schema failure codes](#default-schema-failure-codes). The registry is closed. Each entry states the leading sentence of the English source message, the same way.
 
 ### `ACCENT_COLOR_CHANGED_TOO_MANY_TIMES`
 
@@ -2142,4 +2148,4 @@ A failure raised before the request locale is resolved, such as an IP ban denial
 
 Fluxer localises the `message` of a validation element that has a `code` the same way. A validation element with no `code` has the fixed English string written at the failure site. The `code` field is never localised, either in the envelope or in a validation element.
 
-A code whose catalogue entry is missing for the resolved locale falls back to its English source template. A code with no registered template at all falls back to the message the failure supplied or to the code itself.
+A code whose catalogue entry is missing for the resolved locale falls back to its English source template. Where no template is registered at all, the `message` falls back to the one the failure supplied, or to the code itself.