ably · lmars · Jul 3, 2026 · Jul 3, 2026 · Jul 3, 2026 · Jul 3, 2026
diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml
@@ -25,6 +25,10 @@ jobs:
           npm ci
           npm run lint
           npm run validate:agents
+          npm run validate:errors
+          npm run validate:errors-json
+          npm run generate:errors
+          git diff --exit-code -- protocol/errors.json || { echo 'ERROR: protocol/errors.json is out of date. Run `npm run generate:errors` and commit the result.'; false; }
           npm test
 
   check-go:

diff --git a/errors/CLAUDE.md b/errors/CLAUDE.md
@@ -0,0 +1,28 @@
+# Error code documentation
+
+**Before adding, editing, or reviewing any `<code>.md` file in this directory, read [`guidelines.md`](./guidelines.md).** The rules on title/summary length, tone, and terminology are strict and not all obvious from reading existing entries.
+
+## What this directory holds
+
+The per-code files live in [`codes/`](./codes): one Markdown file per error code, named `<CODE>.md` (e.g. `40142.md`). Each file has YAML frontmatter (`code`, `identifier`, `title`, `summary`) and an optional Markdown body that provides the detail-page content beneath the title and summary. Title, summary, and body conventions are all covered in `guidelines.md`.
+
+The set of files in `codes/` **is the registry** — the source of truth for which codes are valid and what they mean. `protocol/errors.json` is generated from it (a machine-readable map of each code to its `identifier`, `title`, and `summary`); never edit it by hand — run `npm run generate:errors`, which CI enforces via a drift check.
+
+## Conventions at a glance
+
+These are reminders, not substitutes for `guidelines.md`.
+
+- **Filename = code.** `40142.md` must have `code: 40142` in frontmatter.
+- **Identifier** — a stable `snake_case` name (`^[a-z][a-z0-9_]*$`), unique across the registry, the canonical basis for each SDK's generated constant. Name the cause not the consequence; concise but not cryptic; US spelling. A frozen contract — don't churn it, and don't derive it mechanically from the title.
+- **Title** — 3–7 words (cap 10), short phrase or concise subject–verb clause (not necessarily a noun phrase), sentence case, no trailing punctuation, no error-code restatement. Specific enough that a reader can distinguish it from neighbouring errors at a glance.
+- **Summary** — 15–40 words, one or two sentences, plain language. Describe what happened, then (when known) why it might have happened. Don't prescribe remediation — no "Check…", "Verify…", "Retry…". Generic phrasing — the summary represents *every* occurrence of the code, so avoid deictic ("this token", "your channel"); prefer "the token", "the channel". No Markdown formatting, stack traces, or internal identifiers.
+- **Body** (optional) — detail-page content beneath the title and summary. Don't restate either. Order: *What you should do* (lead with the triage — including when the answer is "nothing", for transient/self-healing errors) → *Why it happens* (causes in the reader's terms, each with its fix) → *What you'll see* (message string(s) and status, last, as a findability aid). Link out to feature docs for how-to; no inline code samples. No "related errors" section — disambiguate inline only when codes are genuinely confusable. Describe generically, instruct in second person.
+- **YAML quoting** — single-line summaries don't need quoting unless they start with a special character (`:`, `-`, `[`, `{`, `#`, `&`, `*`, `!`, `|`, `>`, `'`, `"`, `%`, `@`, `` ` ``). In that case wrap the whole summary in double quotes.
+- **Terminology** — use the customer-facing terms from the [Dictionary of terms](https://ably.atlassian.net/wiki/spaces/devex/pages/4295262228/Dictionary+of+terms). Common substitutions: *Region* not site/datacenter/cluster; *Ably Pub/Sub JavaScript SDK* not client library; *Integration* not Reactor/Firehose/integration rule ("rule" now means channel rule); *Token / Basic authentication* not key authentication; *Connection state recovery* not stream resume.
+- **Tone** — plain, calm, specific. Treat copy as product copy, not log messages. Aim for a single consistent voice across the whole directory.
+
+## Reviewing a change
+
+1. Read the table view in your head — does the title disambiguate this error from neighbours? Does the summary stand alone?
+2. Open two or three existing files side-by-side and check that tone, length, and structure match.
+3. Check that the filename matches `code:` and that required fields are present.
diff --git a/errors/README.md b/errors/README.md
@@ -0,0 +1,34 @@
+# Error documentation
+
+This directory is the canonical registry of Ably's error codes and their customer-facing documentation. It is the source of truth for both **which codes are valid** and **what each one means**, used across the wider Ably stack. The registry lives in [`codes/`](./codes) — one Markdown file per valid code — so "is code X valid?" is answered by "does `codes/<code>.md` exist?".
+
+## Registering a new error code
+
+To register a new code, create a Markdown file at `codes/<code>.md` (the filename must be the numeric code, e.g. `codes/40010.md`). It must start with YAML frontmatter containing four required fields:
+
+```markdown
+---
+code: 40010
+identifier: invalid_channel_name
+title: Invalid channel name
+summary: The channel name in the request was not valid, for example because it was empty, contained characters that are not permitted, or used an unknown square-bracketed prefix.
+---
+```
+
+- **`code`** — the numeric error code. Must match the filename.
+- **`identifier`** — a stable, unique `snake_case` name for the code, e.g. `invalid_channel_name`.
+- **`title`** — a short phrase identifying the error at a glance (aim for 3–7 words), e.g. `Invalid channel name`.
+- **`summary`** — one or two plain-language sentences (roughly 15–40 words) covering what happened and, when known, why.
+
+You can add an optional Markdown body beneath the frontmatter for detail-page content (what to do, why it happens). Don't touch `protocol/errors.json` — it is generated from these files; run `npm run generate:errors` to regenerate it after adding or editing a code.
+
+See [`guidelines.md`](./guidelines.md) for the full rules on title, summary, body, tone, and terminology, and run `npm run validate:errors` to check your entry (CI runs both, and fails if `errors.json` is out of date).
+
+## What's in this directory
+
+- [`codes/`](./codes) — the registry: one `<CODE>.md` per valid code.
+- [`guidelines.md`](./guidelines.md) — how to write entries: rules on title, summary, body, tone, and terminology.
+- [`CLAUDE.md`](./CLAUDE.md) — guidance for agents adding, editing, or reviewing entries.
+- [`scripts/`](./scripts) — the validator run in CI.
+
+`protocol/errors.json` is generated from this registry — a machine-readable map of each code to its `identifier`, `title`, and `summary`. It must not be edited by hand; run `npm run generate:errors` to regenerate it, and CI fails if the committed file is out of date.
diff --git a/errors/codes/10000.md b/errors/codes/10000.md
@@ -0,0 +1,6 @@
+---
+code: 10000
+identifier: no_error
+title: No error
+summary: A placeholder code indicating success, used where an error code is expected but the operation completed normally. It does not represent a failure.
+---
diff --git a/errors/codes/101000.md b/errors/codes/101000.md
@@ -0,0 +1,6 @@
+---
+code: 101000
+identifier: space_name_is_empty
+title: Space name is empty
+summary: A space could not be created or referenced because no name was supplied.
+---
diff --git a/errors/codes/101001.md b/errors/codes/101001.md
@@ -0,0 +1,6 @@
+---
+code: 101001
+identifier: space_must_be_entered_first
+title: Space must be entered first
+summary: An operation was attempted that requires having first entered the space. In Ably Spaces, actions such as updating a member's location or profile are only available once the space has been entered.
+---
diff --git a/errors/codes/101002.md b/errors/codes/101002.md
@@ -0,0 +1,6 @@
+---
+code: 101002
+identifier: lock_request_already_pending
+title: Lock request already pending
+summary: A lock could not be requested because a request for the same lock is already in progress. In Ably Spaces, a member may only have one outstanding request for a given lock at a time.
+---
diff --git a/errors/codes/101003.md b/errors/codes/101003.md
@@ -0,0 +1,6 @@
+---
+code: 101003
+identifier: lock_already_held
+title: Lock already held
+summary: A lock could not be acquired because it is currently held by another member. In Ably Spaces, only one member can hold a given lock at a time, and it must be released before another can take it.
+---
diff --git a/errors/codes/101004.md b/errors/codes/101004.md
@@ -0,0 +1,6 @@
+---
+code: 101004
+identifier: lock_invalidated_by_concurrent_request
+title: Lock invalidated by concurrent request
+summary: A lock that appeared to be acquired was invalidated because another member requested the same lock concurrently and now holds it.
+---
diff --git a/errors/codes/102000.md b/errors/codes/102000.md
@@ -0,0 +1,6 @@
+---
+code: 102000
+identifier: invalid_chat_room_name
+title: Invalid chat room name
+summary: A Chat room could not be used because the name supplied for it was not valid.
+---
diff --git a/errors/codes/102001.md b/errors/codes/102001.md
@@ -0,0 +1,6 @@
+---
+code: 102001
+identifier: room_attach_failed_for_messages
+title: Room attach failed for messages
+summary: Attaching a Chat room failed because its messages feature could not be attached.
+---
diff --git a/errors/codes/102002.md b/errors/codes/102002.md
@@ -0,0 +1,6 @@
+---
+code: 102002
+identifier: room_attach_failed_for_presence
+title: Room attach failed for presence
+summary: Attaching a Chat room failed because its presence feature could not be attached.
+---
diff --git a/errors/codes/102003.md b/errors/codes/102003.md
@@ -0,0 +1,6 @@
+---
+code: 102003
+identifier: room_attach_failed_for_reactions
+title: Room attach failed for reactions
+summary: Attaching a Chat room failed because its reactions feature could not be attached.
+---
diff --git a/errors/codes/102004.md b/errors/codes/102004.md
@@ -0,0 +1,6 @@
+---
+code: 102004
+identifier: room_attach_failed_for_occupancy
+title: Room attach failed for occupancy
+summary: Attaching a Chat room failed because its occupancy feature could not be attached.
+---
diff --git a/errors/codes/102005.md b/errors/codes/102005.md
@@ -0,0 +1,6 @@
+---
+code: 102005
+identifier: room_attach_failed_for_typing
+title: Room attach failed for typing
+summary: Attaching a Chat room failed because its typing feature could not be attached.
+---
diff --git a/errors/codes/102050.md b/errors/codes/102050.md
@@ -0,0 +1,6 @@
+---
+code: 102050
+identifier: room_detach_failed_for_messages
+title: Room detach failed for messages
+summary: Detaching a Chat room failed because its messages feature could not be detached.
+---
diff --git a/errors/codes/102051.md b/errors/codes/102051.md
@@ -0,0 +1,6 @@
+---
+code: 102051
+identifier: room_detach_failed_for_presence
+title: Room detach failed for presence
+summary: Detaching a Chat room failed because its presence feature could not be detached.
+---
diff --git a/errors/codes/102052.md b/errors/codes/102052.md
@@ -0,0 +1,6 @@
+---
+code: 102052
+identifier: room_detach_failed_for_reactions
+title: Room detach failed for reactions
+summary: Detaching a Chat room failed because its reactions feature could not be detached.
+---
diff --git a/errors/codes/102053.md b/errors/codes/102053.md
@@ -0,0 +1,6 @@
+---
+code: 102053
+identifier: room_detach_failed_for_occupancy
+title: Room detach failed for occupancy
+summary: Detaching a Chat room failed because its occupancy feature could not be detached.
+---
diff --git a/errors/codes/102054.md b/errors/codes/102054.md
@@ -0,0 +1,6 @@
+---
+code: 102054
+identifier: room_detach_failed_for_typing
+title: Room detach failed for typing
+summary: Detaching a Chat room failed because its typing feature could not be detached.
+---
diff --git a/errors/codes/102100.md b/errors/codes/102100.md
@@ -0,0 +1,6 @@
+---
+code: 102100
+identifier: room_continuity_not_guaranteed
+title: Room continuity not guaranteed
+summary: A discontinuity was detected on the Chat room, so the continuity of messages could not be guaranteed. This usually follows a disconnection long enough that the room could not resume from where it left off.
+---
diff --git a/errors/codes/102101.md b/errors/codes/102101.md
@@ -0,0 +1,6 @@
+---
+code: 102101
+identifier: room_is_in_the_failed_state
+title: Room is in the failed state
+summary: The operation could not be performed because the Chat room is in the failed state. A room enters this state when an earlier operation on it failed and could not recover.
+---
diff --git a/errors/codes/102102.md b/errors/codes/102102.md
@@ -0,0 +1,6 @@
+---
+code: 102102
+identifier: room_is_being_released
+title: Room is being released
+summary: The operation could not be performed because the Chat room is in the process of being released.
+---
diff --git a/errors/codes/102103.md b/errors/codes/102103.md
@@ -0,0 +1,6 @@
+---
+code: 102103
+identifier: room_has_been_released
+title: Room has been released
+summary: The operation could not be performed because the Chat room has already been released.
+---
diff --git a/errors/codes/102104.md b/errors/codes/102104.md
@@ -0,0 +1,6 @@
+---
+code: 102104
+identifier: room_operation_failed_after_earlier_attempt
+title: Room operation failed after earlier attempt
+summary: The operation failed because a preceding attempt to perform it had already failed.
+---
diff --git a/errors/codes/102105.md b/errors/codes/102105.md
@@ -0,0 +1,6 @@
+---
+code: 102105
+identifier: unknown_room_lifecycle_error
+title: Unknown room lifecycle error
+summary: An unexpected error occurred in the Chat room lifecycle that does not correspond to a known condition.
+---
diff --git a/errors/codes/102106.md b/errors/codes/102106.md
@@ -0,0 +1,6 @@
+---
+code: 102106
+identifier: room_released_before_operation_completed
+title: Room released before operation completed
+summary: The operation could not complete because the Chat room was released while it was still in progress.
+---
diff --git a/errors/codes/102107.md b/errors/codes/102107.md
@@ -0,0 +1,6 @@
+---
+code: 102107
+identifier: room_already_exists_with_different_options
+title: Room already exists with different options
+summary: A Chat room with the same name already exists but was created with different options. A room must be released before it can be requested again with a different configuration.
+---
diff --git a/errors/codes/102108.md b/errors/codes/102108.md
@@ -0,0 +1,6 @@
+---
+code: 102108
+identifier: feature_not_enabled_in_room_options
+title: Feature not enabled in room options
+summary: The operation required a feature that was not enabled when the Chat room was created. Features such as presence or typing indicators must be enabled in the room options to be used.
+---
diff --git a/errors/codes/102109.md b/errors/codes/102109.md
@@ -0,0 +1,6 @@
+---
+code: 102109
+identifier: history_requested_for_an_unsubscribed_listener
+title: History requested for an unsubscribed listener
+summary: A request for the messages published before a listener's subscription point was rejected because that listener was not subscribed. This history is only available while the listener is subscribed to the room.
+---
diff --git a/errors/codes/102110.md b/errors/codes/102110.md
@@ -0,0 +1,6 @@
+---
+code: 102110
+identifier: channel_serial_not_defined
+title: Channel serial not defined
+summary: A channel serial was expected but was not defined at the point it was needed.
+---
diff --git a/errors/codes/102111.md b/errors/codes/102111.md
@@ -0,0 +1,6 @@
+---
+code: 102111
+identifier: channel_options_modified_after_request
+title: Channel options modified after request
+summary: Channel options could not be changed because the underlying channel had already been requested.
+---
diff --git a/errors/codes/102112.md b/errors/codes/102112.md
@@ -0,0 +1,6 @@
+---
+code: 102112
+identifier: room_is_in_an_invalid_state
+title: Room is in an invalid state
+summary: The operation could not be performed because the Chat room was in a state that does not permit it.
+---
diff --git a/errors/codes/102113.md b/errors/codes/102113.md
@@ -0,0 +1,6 @@
+---
+code: 102113
+identifier: sequential_execution_could_not_be_enforced
+title: Sequential execution could not be enforced
+summary: The operation failed because its sequential execution could not be enforced. Chat room lifecycle operations are expected to run one at a time, and that ordering could not be guaranteed.
+---
diff --git a/errors/codes/102200.md b/errors/codes/102200.md
@@ -0,0 +1,6 @@
+---
+code: 102200
+identifier: hook_used_outside_its_provider
+title: Hook used outside its provider
+summary: An Ably Chat React hook was used in a component that is not wrapped in the required provider. The hooks depend on context supplied by a provider higher in the component tree.
+---
diff --git a/errors/codes/102201.md b/errors/codes/102201.md
@@ -0,0 +1,6 @@
+---
+code: 102201
+identifier: component_unmounted_before_completion
+title: Component unmounted before completion
+summary: An operation started by the Ably Chat React hooks could not finish because the React component was unmounted while it was still in progress.
+---
diff --git a/errors/codes/102202.md b/errors/codes/102202.md
@@ -0,0 +1,6 @@
+---
+code: 102202
+identifier: presence_data_could_not_be_fetched
+title: Presence data could not be fetched
+summary: The Ably Chat React hooks could not retrieve presence data after the maximum number of retries. This usually points to a persistent problem reaching presence rather than a transient one.
+---
diff --git a/errors/codes/103000.md b/errors/codes/103000.md
@@ -0,0 +1,6 @@
+---
+code: 103000
+identifier: unable_to_publish_push_notification
+title: Push notification internal error
+summary: The push notification was not delivered because of an unexpected error within the Ably platform during preparation, dispatch, or requeue. The cause is not related to the contents of the request or the device's registration.
+---
diff --git a/errors/codes/103001.md b/errors/codes/103001.md
@@ -0,0 +1,6 @@
+---
+code: 103001
+identifier: push_publish_retries_exhausted
+title: Push notification retry limit reached
+summary: The push notification was not delivered because the configured retry limit was reached after repeated unsuccessful delivery attempts. The underlying failures are typically transient — provider outages, rate limits, or network errors.
+---
diff --git a/errors/codes/103002.md b/errors/codes/103002.md
@@ -0,0 +1,6 @@
+---
+code: 103002
+identifier: push_direct_publish_no_recipient
+title: Push notification recipient missing
+summary: The push notification was not delivered because the direct push request was submitted without a recipient device. Direct push targets a single device by ID and cannot be processed when no recipient is supplied.
+---
diff --git a/errors/codes/103003.md b/errors/codes/103003.md
@@ -0,0 +1,6 @@
+---
+code: 103003
+identifier: push_cannot_handle_body
+title: Push notification body invalid
+summary: The push notification was not delivered because its body could not be processed. This typically indicates a malformed or unsupported message structure in the publish request.
+---
diff --git a/errors/codes/103004.md b/errors/codes/103004.md
@@ -0,0 +1,6 @@
+---
+code: 103004
+identifier: push_notification_rejected_by_provider
+title: Push notification rejected by provider
+summary: The push notification was not delivered because the provider — APNs, FCM, or WebPush — rejected the request due to a problem with the payload or delivery parameters. Typical causes include an oversized payload, a disallowed topic, or an unsupported field.
+---
diff --git a/errors/codes/103005.md b/errors/codes/103005.md
@@ -0,0 +1,6 @@
+---
+code: 103005
+identifier: push_device_token_invalid
+title: Push device token invalid
+summary: The push notification was not delivered because the provider — APNs, FCM, or WebPush — rejected the device's push token as invalid for the configured application. The token may have been issued under different credentials or for a different application.
+---
diff --git a/errors/codes/103006.md b/errors/codes/103006.md
@@ -0,0 +1,6 @@
+---
+code: 103006
+identifier: push_transport_not_configured
+title: Push transport not configured
+summary: The push notification was not delivered because the device's push notification provider — APNs, FCM, or WebPush — has no credentials configured on the application. No deliveries can be made through that provider until the credentials are present.
+---
diff --git a/errors/codes/103007.md b/errors/codes/103007.md
@@ -0,0 +1,6 @@
+---
+code: 103007
+identifier: push_notification_provider_unreachable
+title: Push notification provider unreachable
+summary: The push notification was not delivered because the provider — APNs, FCM, or WebPush — could not be reached, returned a server error, or sent a response that could not be processed. The condition is usually transient.
+---
diff --git a/errors/codes/103008.md b/errors/codes/103008.md
@@ -0,0 +1,6 @@
+---
+code: 103008
+identifier: push_transport_credentials_invalid
+title: Push transport credentials invalid
+summary: A push notification could not be sent because the credentials configured for the target platform were rejected or had expired, such as an expired APNs certificate.
+---
diff --git a/errors/codes/20000.md b/errors/codes/20000.md
@@ -0,0 +1,6 @@
+---
+code: 20000
+identifier: general_error
+title: General error
+summary: A generic error that does not correspond to a more specific code. It is used as a catch-all when the condition could not be classified more precisely.
+---
diff --git a/errors/codes/40000.md b/errors/codes/40000.md
@@ -0,0 +1,6 @@
+---
+code: 40000
+identifier: bad_request
+title: Bad request
+summary: The request was rejected because it was invalid and could not be processed.
+---
diff --git a/errors/codes/40001.md b/errors/codes/40001.md
@@ -0,0 +1,6 @@
+---
+code: 40001
+identifier: invalid_request_body
+title: Invalid request body
+summary: The body of the request could not be processed because it was invalid, missing required fields, or not in the expected format.
+---