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