Error code documentation registry

[lmars]

Summary

Introduces a single registry for Ably error codes under errors/ and makes it the source of truth. Each valid code is a Markdown file at errors/codes/<code>.md with code, identifier, title and summary frontmatter, plus an optional Markdown body for detail-page content.

Examples:

• 40142: Token Expired
• 40160: Client lacks the required capability
• 90003: Channel continuity not guaranteed

protocol/errors.json is now generated from this registry, so the set of codes and their descriptions can no longer drift between the two (a drift we hit and fixed in this branch — 40115).

This is the ably-common groundwork for rendering error documentation in the docs site and giving SDKs a single place to source error codes and their names.

Note to reviewers

This adds a Markdown file for every error code from the existing errors.json file that have either already been reviewed in the realtime repo (e.g. see https://github.com/ably/realtime/pull/8461, https://github.com/ably/realtime/pull/8479, and https://github.com/ably/realtime/pull/8512), or that I've had Claude generate and personally reviewed.

Feel free to review those individual Markdown files, but the thing I'm really interested in is the new registry structure:

• the fact that registering an error code now involves creating a Markdown file
• the guidelines for writing those Markdown files, including a required identifier for referring to the error code by name rather than by number in realtime and SDK code
• the updated error.json which is now auto-generated from the Markdown files in a backwards-incompatible way (see below)

If you do leave comments on the wording of the individual errors, please leave those with an approval and I will create tickets to address those separately.

What's in here

• errors/codes/*.md — the registry. One file per code (254 in total), covering everything in errors.json and seeded from the curated entries authored in the realtime repo. code, identifier, title and summary are required; the body is optional.
• identifier — a stable, unique snake_case name per code (e.g. token_expired), the canonical basis for the constant each SDK generates. Chosen deliberately rather than derived from the title, so it's a frozen contract that doesn't churn when copy is reworded. Seeded from existing SDK/server constants where they existed, then normalised.
• US spelling across all entries, per the documentation style guide.
• Validation in CI (errors/scripts/validate-errors.js): filename ↔ code, required fields, identifier format and uniqueness, and title/summary length warnings.
• protocol/errors.json is generated from the registry (errors/scripts/generate-errors-json.js, npm run generate:errors), with a JSON schema and a drift guard — CI regenerates it and fails if the committed file is out of date, so it can't be hand-edited out of sync.
• Docs: errors/README.md, errors/guidelines.md and errors/CLAUDE.md describe the registry and how to add and write entries.

errors.json structure change (breaking for parsers)

protocol/errors.json changes from a flat code → title map to a keyed object carrying the new fields:

{
  "codes": {
    "40142": { "identifier": "token_expired", "title": "Token expired", "summary": "…" }
  }
}

Consumers that only link to the file are unaffected. Consumers that parse it need updating — as follow-ups in their own repos:

• ably-go / ably-ruby — update their error-code generators to read the new shape and adopt identifier for constant names.
• ably-ai-transport-js — move from a runtime key-lookup to generating its enum from identifier.
• top-error-codes dashboard (ours) — reads code → title.

🤖 Generated with Claude Code

[lmars]

Here's a docs PR built on top of this which renders these error Markdown files within the docs site:

ably/docs#3458

[m-hulbert]

Had a read through all the related docs and overall looks good to me.

I didn't read through every error description, but scanned through them all, and dropped a few comments. Most are very minor and non-blocking - with one exception on the identifier for a specific error.

My only pushback would be that I think we should mandate a body being added for new errors going forwards, rather than making it optional. Otherwise all the work you'll be putting in to backfill them will need to be repeated at some point.

[m-hulbert]

I'd prefer not to have 'mutable messages' exposed externally at all if possible.

[lmars]

Ok, updated to message_updates_not_enabled in 1abd681.

[m-hulbert]

This is a bit of a mouthful with "the channel namespace's..."

Can we not go with something like "An operation could not be performed because the channel did not have the 'Message annotations, updates appends, and deletes' rule enabled."

[lmars]

Applied your suggestion in 1abd681.

[m-hulbert]

Very minor, but we'd code style untilAttach in docs.

[lmars]

Backtickified in 1abd681.

[m-hulbert]

This would read better as shorter sentences rather than all the hyphens and commas.

[lmars]

Yeh, updated in 1abd681.

[umair-ably]

I only focused on the guidelines and a single md example, but this is great!

Big fan of how the body has been structured too. Just wanted to call out we've still got "What you should do" instead of "remediation". I think this is fine and better suits the content and writing style here. Just highlighting that ably-js will have a remediation property as previously discussed but this diversion between the two is fine imo