docs: correct misreadable and factually wrong reference prose (#2587)

2026-10-18 21:45:31 +09:00 · 2026-09-08 15:36:50 +02:00
1 parent 43924e3ac5
commit 08c9fe9886
@@ -257,7 +257,7 @@ Every rejection reports the same `INVALID_TOKEN`, so a caller cannot distinguish

 <RouteHeader method="GET" path="/v1/oauth2/applications/{id}/public" unauthenticated />

-Returns the [public application](#public-application-object) object for any application. Authentication is not required. A credential that resolves to an account also populates `current_user` and reports the owner's view of `bot_public`.
+Returns the [public application](#public-application-object) object for any application. Authentication is not required. A credential that resolves to an account also populates `current_user`, and one that resolves to the application owner reports `bot_public` as true even when the bot is not public.

 ### Path parameters

@@ -856,7 +856,7 @@ The operation creates one 64-character verification token bound to the account a

 Accepts a password recovery request for an email address. Authentication is not required. Returns 204 with no body.

-This is a local authentication operation and it verifies CAPTCHA when CAPTCHA is enabled. Fluxer consumes both extra allowances before it validates the address, and exhausting either returns 429.
+This is a local authentication operation and it verifies CAPTCHA when CAPTCHA is enabled. Fluxer consumes both the client IP address and email address allowances before it validates the address, and exhausting either returns 429.

 ### Request headers

@@ -496,7 +496,7 @@ Refunds the account's most recent eligible purchase and returns the [refund](#re

 The same invoice selection as [get refund eligibility](#get-refund-eligibility) applies.

-Repeating the request returns the same provider refund. After a refund the provider reports as failed or cancelled, the account can attempt the refund again.
+Repeating the request returns the same provider refund. After a refund that the provider reports as failed or cancelled, the account can attempt the refund again.

 :::note[A Pix refund is short one minor unit]
 When the resolved charge was paid with Pix and the invoice amount is greater than one minor unit, the requested refund is the invoice amount minus one minor unit.
@@ -174,7 +174,7 @@ The slowmode state combines the channel's configured interval with the authentic

 <sup>1</sup> Both report no delay in a private channel, for an interval of `0`, for a bot caller, and for a caller holding `BYPASS_SLOWMODE`

-<sup>2</sup> False whenever the delay is not accounted, so a bot caller and a private channel both report `false` even though neither is delayed
+<sup>2</sup> True only for a non-bot caller holding `BYPASS_SLOWMODE` in a guild channel with a non-zero interval, so a bot caller and a private channel both report `false` even though neither is delayed

 ### Example

@@ -118,7 +118,7 @@ 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 257 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 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.

 :::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.
@@ -6,7 +6,7 @@ description: Guild audit log entries, their action registry, and the audit reaso

 import RouteHeader from '@/components/RouteHeader.astro';

-An audit log entry records one change made to a guild and the account that made it. It has a numeric action type, the ID of the thing changed, an option map, and a list of before-and-after values. Only [List guild audit logs](#list-guild-audit-logs) reads them.
+An audit log entry records one change made to a guild and the account that made it. It has a numeric action type, the ID of the thing changed, an option map, and a list of before-and-after values. Only [List guild audit logs](#list-guild-audit-logs) and its [Admin API counterpart](/admin-api/guilds/#list-guild-audit-logs) read them.

 ## Audit log reason

@@ -191,7 +191,7 @@ Every field is optional, and an omitted filter is not applied. The route reads a

 <sup>7</sup> The sort field is camel-cased `joinedAt`, where the result object names the same value `joined_at`

-[Input normalisation](/http-api/#input-normalisation) rewrites `""` to null, which this field rejects with 400 `INVALID_FORM_BODY`. `" "` is accepted.
+[Input normalisation](/http-api/#input-normalisation) rewrites `""` to null, which the `query` field rejects with 400 `INVALID_FORM_BODY`. `" "` is accepted.

 With no `sort_by`, the route sorts by join time and defaults `sort_order` to `desc`. Two members with the same join time are ordered by descending `id`. `relevance` ignores `sort_order`. A Meilisearch instance orders `relevance` by its own ranking rules. An Elasticsearch instance orders `relevance` by descending `id`.

@@ -81,7 +81,7 @@ An empty string stays an empty string and an empty nested object stays an empty

 [Authentication](/authentication/) defines the accepted `Authorization` schemes, their exact token forms, and the OAuth2 scope registry. An operation that requires a credential states the scheme on its resource page. The [sudo verification object](/http-api/users/mfa/#sudo-verification-object) defines the sudo mode credential that guards sensitive account operations.

-An OAuth2 bearer access token is accepted only where a route opts in, and the resource page says so. Everywhere else a bearer credential is refused with 403 `ACCESS_DENIED`, and an account with a suspicious activity flag is refused with 403 `ACCOUNT_SUSPICIOUS_ACTIVITY`.
+An OAuth2 bearer access token is accepted only where a route opts in, and the resource page says so. Everywhere else a bearer credential is refused with 403 `ACCESS_DENIED`. An account with a suspicious activity flag is refused with 403 `ACCOUNT_SUSPICIOUS_ACTIVITY`.

 ## Standard request headers

@@ -117,9 +117,9 @@ A reply reference resolves into `referenced_message`, and a forward has none. Fl
 | 7 | USER_JOIN<sup>2</sup> | User-join system message |
 | 19 | REPLY<sup>1</sup> <sup>2</sup> | Message with a reply reference |

-<sup>1</sup> Only this type can be modified, pinned, unpinned, or used as the target of a reply reference. Any other type rejects modification, pinning, and unpinning with 400 `CANNOT_MODIFY_SYSTEM_WEBHOOK`, and rejects being replied to with 400 `CANNOT_REPLY_TO_SYSTEM_MESSAGE`
+<sup>1</sup> Only `DEFAULT` and `REPLY` can be modified, pinned, unpinned, or used as the target of a reply reference. Any other type rejects modification, pinning, and unpinning with 400 `CANNOT_MODIFY_SYSTEM_WEBHOOK`, and rejects being replied to with 400 `CANNOT_REPLY_TO_SYSTEM_MESSAGE`

-<sup>2</sup> Only this type can be deleted, and any other type rejects deletion with 403 `MISSING_PERMISSIONS`
+<sup>2</sup> Only `DEFAULT`, `CHANNEL_PINNED_MESSAGE`, `USER_JOIN`, and `REPLY` can be deleted, and any other type rejects deletion with 403 `MISSING_PERMISSIONS`

 ## Message flags

@@ -1008,7 +1008,7 @@ Fluxer aborts the multipart upload and discards its parts when no part was uploa
 :::

 :::caution[An unowned upload is reported as invalid input]
-An upload key the identity does not own, that belongs to another channel, that was planned as singlepart, or that a message already consumed all report 400 `UPLOADED_ATTACHMENT_NOT_FOUND`. A caller cannot tell the four apart, so it cannot probe another identity's upload state.
+Fluxer reports 400 `UPLOADED_ATTACHMENT_NOT_FOUND` for an upload key the identity does not own, one that belongs to another channel, one planned as singlepart, and one a message already consumed. A caller cannot tell the four apart, so it cannot probe another identity's upload state.
 :::

 ### Side effects
@@ -58,7 +58,7 @@ An unrecognised scope value is rejected when the authorisation request is comple
 Scope order has no semantic meaning, so a client MUST compare scopes as a set.
 :::

-The `scope` string of an [OAuth2 token](#oauth2-token-object) and of an [OAuth2 introspection](#oauth2-introspection-object) is sorted into the registry order above. The `scopes` array of a [current OAuth2 authorisation](#current-oauth2-authorisation-object) and of an [OAuth2 authorisation](#oauth2-authorisation-object) has the stored scopes in no defined order, with unrecognised values removed.
+The `scope` string of an [OAuth2 token](#oauth2-token-object) and of an [OAuth2 introspection](#oauth2-introspection-object) is sorted into the registry order above. The `scopes` array of a [current OAuth2 authorisation](#current-oauth2-authorisation-object) has the stored scopes in no defined order, with unrecognised values removed. The `scopes` array of an [OAuth2 authorisation](#oauth2-authorisation-object) is in no defined order, and it can hold `bot` and an unrecognised value once more than one refresh token contributes.

 ## OAuth2 error response object

@@ -97,7 +97,7 @@ The single credential [Create DSA report](#create-dsa-report) accepts. Fluxer bi
 | --- | --- | --- |
 | ticket<sup>1</sup> | string | The opaque credential [Create DSA report](#create-dsa-report) consumes |

-<sup>1</sup> 64 lowercase hexadecimal characters encoding 32 random bytes, valid for one hour from verification, and consumed by the first [Create DSA report](#create-dsa-report) that presents it
+<sup>1</sup> 64 lowercase hexadecimal characters encoding 32 random bytes, valid for one hour from verification, and consumed by the first [Create DSA report](#create-dsa-report) that writes a notice with it

 ### Example

@@ -310,7 +310,7 @@ The operation is active only while the instance has presigned harvest downloads
 The token binds the account, the harvest ID, the stored object key, and an expiry.

 :::note[Every rejection looks identical]
-A missing, malformed, forged, or expired token, a token for another harvest, a harvest that never completed or recorded a failure, a harvest past its deadline, and a stale object key all return 404 with the plain text body `Not Found`.
+A missing, malformed, forged, or expired token, a token for another harvest, a harvest that never completed, a harvest that recorded a failure, a harvest past its deadline, and a stale object key all return 404 with the plain text body `Not Found`.
 :::

 ### Path parameters
@@ -80,7 +80,7 @@ Opens a direct message with one account, or creates a group DM. Returns a [chann

 One body field selects the channel type. `recipient_id` opens a direct message. `recipients` always creates a group DM whatever its length, so a single-element array creates a two-participant group DM, and an empty array creates a group DM whose only participant is the caller.

-A request supplying `recipients` additionally consumes the `user:group_dm:create` bucket and passes the CAPTCHA check below, whatever the resulting participant count.
+A request supplying `recipients` additionally consumes the `user:group_dm:create` bucket and is subject to the CAPTCHA check below, whatever the resulting participant count.

 Instance policy can disable private channel creation entirely, in which case every request returns 400 `DIRECT_MESSAGES_DISABLED` after the body has been validated and the group DM bucket and CAPTCHA have been applied.