Register error code 40167 for untrusted client type declarations

[SimonWoolf]

Adds error code 40167 (untrusted_client_type_declaration), needed by the realtime implementation of PSDR22: Differentiating users from servers for MAU billing.

Why a new code

PSDR22 classifies every connection and request as device (the default) or server, and this determines whether traffic counts toward MAU and whether it is subject to per-client-ID limits. Because a client must not be able to exempt itself, the trust model differs by auth type:

• Token auth — the signed x-ably-clientType=server claim is the only trusted declaration. A clientType=server param or a -server agent identifier arriving without the claim is rejected with an actionable error, rather than silently honoured or ignored. That rejection is what this code reports.
• API-key auth — every signal is trusted, since the caller holds the key.

The rejection is deliberately loud in both directions: it catches an end user attempting to exempt themselves, and equally a server misconfigured onto token auth without the claim.

Why 40167 specifically

Placed in the 4016x family of insufficient-credential errors, next to its closest neighbours:

• 40161 (identified_client_required) is the clientId gate — a different rejection that the same feature also uses.
• 40166 (unidentified_client_cannot_modify_own_messages) is about "own" capabilities.

Neither fits, and no existing code covers "the credential presented cannot grant the declaration being made". 40167 was free.

Notes

• protocol/errors.json is regenerated via npm run generate:errors, not hand-edited.
• The What you'll see section gives the code and HTTP status only. The message string is deliberately omitted rather than guessed, since the raising code in ably/realtime is not written yet; per the guidelines, message strings should be verified against their source. Happy to add it in a follow-up once that lands.
• validate:errors, validate:errors-json, format:data:check, markdownlint and jest all pass.

🤖 Generated with Claude Code

[lmars]

I think this should mention that the developer needs to be using JWT auth, and link to our docs for how to add claims to a JWT token.

I also think "rather than declaring the client type alongside the token" might not be obvious if the developer used a server-side SDK rather than explicitly setting clientType=server themselves.

[SimonWoolf]

reworded.
(i've added a para on if you're accidentally using a Server SDK for a non-server you should switch to a Device SDK, would like to link to docs on that but I assume they don't exist yet)