Skip to content

Updated errors to use new auto-generated docs #318

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Updated errors to use new auto-generated docs #318

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7a8e337
Updated errors to use new auto-generated docs
mattheworiordan Aug 24, 2025
7c0fc06
Explain how `ably-os errors` is now used to maintain error codes
mattheworiordan Aug 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions protocol/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,26 @@ In addition, a list of error codes and corresponding support articles to help un
This ensures that with every Ably error message that includes a help link for the error in the format `https://help.ably.io/error/{{ERROR_CODE}}`, the user is taken to a relevant FAQ if it exists, and if one does not exist, we record the number of times that error code has been visited so that the docs/support team can work on adding relevant documentation.
See [the `ably/help` repository (internal)](https://github.com/ably/help), the "simple help redirect site".

### Error Code Management

**IMPORTANT**: Error codes and their definitions are now automatically managed by the [ably-os error documentation system](https://github.com/ably/ably-os/blob/main/docs/ERROR_COMMANDS_GUIDE.md). The files [errors.json](./errors.json) and [errorsHelp.json](./errorsHelp.json) are automatically updated from the ably-os system.

**Do not manually edit these files directly.** Instead:

1. **For error code updates**: Use the ably-os error commands to regenerate and update centralized error definitions:
```bash
# From the ably-os repository:
ably-os errors aggregate-error-data # Consolidate all error data
ably-os errors update-ably-common # Update this repository's JSON files
```

2. **For new error code ranges or categories**: When adding new error code ranges or categories:
- Add the range definition to this README file (see Ranges section below)
- Also add the category to the ably-os error categorization system: [`src/prompts/errors/error-docs-context.md`](https://github.com/ably/ably-os/blob/main/src/prompts/errors/error-docs-context.md)
- This ensures consistency between the protocol documentation and the automated error documentation system

3. **For comprehensive error documentation**: The ably-os system generates individual error pages at `https://ably.com/docs/platform/errors/codes/[CODE]-[slug]` with detailed explanations, causes, and solutions.

If you need help understanding any error codes, or need technical support, please visit the [Ably support desk](https://www.ably.io/support).

### Ranges
Expand Down
266 changes: 131 additions & 135 deletions protocol/errors.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,134 +1,128 @@
{
"10000": "no error",

"20000": "general error code",

"40000": "bad request",
"40001": "invalid request body",
"0": "Generic client error",
"1": "Unknown error",
"10000": "No error (operational state)",
"10200": "Unrecognized error code",
"20000": "Informational status",
"40000": "Bad request",
"40001": "Invalid request body",
"40002": "invalid parameter name",
"40003": "invalid parameter value",
"40004": "invalid header",
"40005": "invalid credential",
"40006": "invalid connection id",
"40003": "Invalid Parameter Value",
"40004": "Invalid header",
"40005": "Invalid credential",
"40006": "Invalid connection ID",
"40007": "invalid message id",
"40008": "invalid content length",
"40009": "maximum message length exceeded",
"40010": "invalid channel name",
"40011": "stale ring state",
"40012": "invalid client id",
"40008": "Invalid content length",
"40009": "Message size exceeded",
"40010": "Invalid channel name",
"40011": "Stale ring state or invalid data payload",
"40012": "Invalid client ID",
"40013": "Invalid message data or encoding",
"40014": "Resource disposed",
"40015": "Invalid device id",
"40015": "Invalid device ID",
"40016": "Invalid message name",
"40017": "Unsupported protocol version",
"40018": "Unable to decode message; channel attachment no longer viable",
"40019": "Required client library plugin not present",
"40020": "Batch error",
"40018": "Delta decode failure",
"40019": "Missing Plugin",
"40020": "Batch operation partial failure",
"40021": "Feature requires a newer platform version",
"40022": "API Streamer has been shut down",
"40023": "Action requires a newer protocol version",
"40030": "Invalid publish request (unspecified)",
"40031": "Invalid publish request (invalid client-specified id)",
"40032": "Invalid publish request (impermissible extras field)",
"40022": "Invalid Resource or Deprecated Feature",
"40023": "Protocol Version Required",
"40024": "Channel Mode Required",
"40030": "Invalid publish request",
"40031": "Invalid message ID",
"40032": "Invalid extras field",
"40033": "Operation cancelled",
"40034": "Invalid publish request (maximum number of messages per ChannelMessage exceeded)",
"40099": "Reserved for artifical errors for testing",

"40100": "unauthorized",
"40101": "invalid credentials",
"40102": "incompatible credentials",
"40103": "invalid use of Basic auth over non-TLS transport",
"40104": "timestamp not current",
"40099": "Internal Testing Error",
"40100": "Unauthorized access",
"40101": "Invalid credentials",
"40102": "Incompatible credentials",
"40103": "Basic authentication requires TLS",
"40104": "Timestamp not current",
"40105": "nonce value replayed",
"40106": "Unable to obtain credentials from given parameters",
"40106": "Missing authentication credentials",
"40110": "account disabled",
"40111": "account restricted (connection limits exceeded)",
"40112": "account blocked (message limits exceeded)",
"40113": "account blocked",
"40113": "Account blocked",
"40114": "account restricted (channel limits exceeded)",
"40115": "maximum number of permitted applications exceeded",
"40115": "Account request limit exceeded",
"40120": "application disabled",
"40121": "token revocation not enabled for this application",
"40121": "Token revocation not enabled",
"40125": "maximum number of rules per application exceeded",
"40126": "maximum number of namespaces per application exceeded",
"40127": "maximum number of keys per application exceeded",
"40130": "key error (unspecified)",
"40131": "key revoked",
"40132": "key expired",
"40133": "key disabled",
"40133": "wrong key; cannot revoke tokens with a different key to the one that issued them",
"40140": "token error (unspecified)",
"40130": "Key removed",
"40131": "Key revoked",
"40132": "API key expired",
"40133": "Token revocation authorization error",
"40140": "Token error (unspecified)",
"40141": "token revoked",
"40142": "token expired",
"40142": "Token expired",
"40143": "token unrecognised",
"40144": "invalid JWT format",
"40144": "Invalid JWT token format",
"40145": "invalid token format",
"40146": "Unsupported token claims",
"40149": "Token error range boundary",
"40150": "connection blocked (limits exceeded)",
"40160": "operation not permitted with provided capability",
"40161": "operation not permitted as it requires an identified client",
"40162": "operation not permitted with a token, requires basic auth",
"40160": "Insufficient capabilities",
"40161": "Namespace Requires Identified Clients",
"40162": "Token revocation requires basic authentication",
"40163": "operation not permitted, key not marked as permitting revocable tokens",
"40164": "channel state disabled",
"40170": "error from client token callback",
"40171": "no means provided to renew auth token",
"40164": "API key missing revocable tokens attribute",
"40170": "Authentication callback error",
"40171": "Token renewal not configured",
"40172": "operation only permitted with token auth",
"40180": "unable to send location notification; location notifications can only be sent using token authentication",
"40181": "unable to send location notification; no location token for device",

"40300": "forbidden",
"40300": "Forbidden",
"40310": "account does not permit tls connection",
"40311": "operation requires tls connection",
"40320": "application requires authentication",
"40330": "unable to activate account due to placement constraint (unspecified)",
"40331": "unable to activate account due to placement constraint (incompatible environment)",
"40332": "unable to activate account due to placement constraint (incompatible site)",

"40400": "not found",

"40500": "method not allowed",

"40331": "Placement constraint environment error",
"40332": "Placement Constraint Violation",
"40400": "Resource not found",
"40500": "Method Not Allowed",
"40800": "Request timeout",
"40900": "conflict",

"41001": "push device registration expired",

"42200": "unprocessable content",
"42210": "content rejected (unspecified)",
"42211": "content rejected by before publish rule",
"42211": "Message rejected by before-publish rule",
"42212": "content rejected by validation",
"42213": "content rejected by moderation",

"42213": "Message rejected by moderation",
"42910": "rate limit exceeded (nonfatal): request rejected (unspecified)",
"42911": "max per-connection publish rate limit exceeded (nonfatal): unable to publish message",
"42912": "there is a channel iteration call already in progress; only 1 active call is permitted to execute at any one time",
"42920": "rate limit exceeded (fatal)",
"42921": "max per-connection publish rate limit exceeded (fatal); closing connection",
"42922": "rate limit exceeded; too many requests",

"50000": "internal error",
"50001": "internal channel error",
"50002": "internal connection error",
"50003": "timeout error",
"50004": "Request failed due to overloaded instance",
"50005": "Service unavailable (service temporarily in lockdown)",

"50010": "Ably's edge proxy service has encountered an unknown internal error whilst processing the request",
"50210": "Ably's edge proxy service received an invalid (bad gateway) response from the Ably platform",
"50310": "Ably's edge proxy service received a service unavailable response code from the Ably platform",

"42922": "Rate limit exceeded - too many requests",
"49900": "Call cancelled",
"50000": "Internal server error",
"50001": "Internal Channel Error",
"50002": "Internal connection error",
"50003": "Timeout error",
"50004": "Service Unavailable (Capacity Limit)",
"50005": "Service in lockdown",
"50010": "Internal server error",
"50210": "Bad Gateway",
"50300": "Service Unavailable",
"50310": "Edge service unavailable",
"50320": "Active Traffic Management: traffic for this cluster is being temporarily redirected to a backup service",

"50330": "request reached the wrong cluster; retry (used during dns changes for cluster migrations)",

"50410": "Ably's edge proxy service timed out waiting for the Ably platform",

"50400": "Gateway Timeout",
"50410": "Edge proxy gateway timeout",
"61002": "Push activation clientId mismatch",
"65536": "Not an error code",
"70000": "reactor operation failed",
"70001": "reactor operation failed (post operation failed)",
"70002": "reactor operation failed (post operation returned unexpected code)",
"70003": "reactor operation failed (maximum number of concurrent in-flight requests exceeded)",
"70004": "reactor operation failed (invalid or unaccepted message contents)",
"70005": "unable to deliver AMQP message (unspecified timeout)",
"70006": "unable to deliver AMQP message (cluster busy)",

"70003": "Integration max concurrency exceeded",
"70004": "Integration Invalid Message Content",
"70005": "AMQP queue timeout",
"70006": "AMQP broker backpressure",
"71000": "Exchange error (unspecified)",
"71001": "Forced re-attachment due to permissions change",
"71100": "Exchange publisher error (unspecified)",
Expand All @@ -143,7 +137,6 @@
"71301": "Subscription disabled",
"71302": "Requester has no subscription to this product",
"71303": "Channel does not match the channel filter specified in the subscription to this product",

"72000": "ingress operation failed",
"72001": "ingress failed to publish message",
"72002": "ingress table is unhealthy",
Expand All @@ -153,69 +146,71 @@
"72006": "unable to resume from change stream",
"72007": "unable to store change stream resume token",
"72008": "change stream history lost",

"80000": "connection failed",
"80000": "Connection failed",
"80001": "connection failed (no compatible transport)",
"80002": "connection suspended",
"80003": "disconnected",
"80002": "Connection suspended",
"80003": "Connection temporarily unavailable",
"80004": "already connected",
"80005": "invalid connection id (remote not found)",
"80006": "unable to recover connection (messages expired)",
"80007": "unable to recover connection (message limit exceeded)",
"80008": "unable to recover connection (connection expired)",
"80009": "connection not established (no transport handle)",
"80010": "invalid operation (invalid transport handle)",
"80008": "Connection recovery expired",
"80009": "Connection transport unavailable",
"80010": "Invalid transport handle",
"80011": "unable to recover connection (incompatible auth params)",
"80012": "unable to recover connection (invalid or unspecified connection serial)",
"80013": "protocol error",
"80014": "connection timed out",
"80013": "Protocol Error",
"80014": "Connection timeout",
"80015": "incompatible connection parameters",
"80016": "operation on superseded connection",
"80017": "connection closed",
"80018": "invalid connection id (invalid format)",
"80019": "client configured authentication provider request failed",
"80016": "Operation on Superseded Connection",
"80017": "Connection closed",
"80018": "Invalid connection ID",
"80019": "Authentication provider request failed",
"80020": "continuity loss due to maximum subscribe message rate exceeded",
"80021": "exceeded maximum permitted account-wide rate of creating new connections",
"80022": "unable to continue current comet connection",
"80023": "unable to resume connection from a different site",
"80023": "Unable to resume connection from another site",
"80030": "client restriction not satisfied",

"90000": "channel operation failed",
"90001": "channel operation failed (invalid channel state)",
"90000": "Channel operation failed",
"90001": "Channel operation failed (invalid channel state)",
"90002": "channel operation failed (epoch expired or never existed)",
"90003": "unable to recover channel (messages expired)",
"90004": "unable to recover channel (message limit exceeded)",
"90005": "unable to recover channel (no matching epoch)",
"90003": "Unable to recover channel (messages expired)",
"90004": "Message Limit Exceeded",
"90005": "Channel Recovery Epoch Not Found",
"90006": "unable to recover channel (unbounded request)",
"90007": "channel operation failed (no response from server)",
"90010": "maximum number of channels per connection/request exceeded",
"90007": "Channel operation timeout",
"90010": "Channel limit exceeded",
"90021": "exceeded maximum permitted account-wide rate of creating new channels",
"91000": "unable to enter presence channel (no clientId)",
"91001": "unable to enter presence channel (invalid channel state)",
"90099": "Generic discontinuity",
"91000": "Presence requires client ID",
"91001": "presence-channel-invalid-state",
"91002": "unable to leave presence channel that is not entered",
"91003": "unable to enter presence channel (maximum member limit exceeded)",
"91004": "unable to automatically re-enter presence channel",
"91005": "presence state is out of sync",
"91100": "member implicitly left presence channel (connection closed)",

"92000": "invalid object message",
"92001": "objects limit exceeded",
"92002": "unable to submit operation on tombstone object",
"92003": "unable to fetch object tree with tombstone object as root",
"92004": "object not found",
"92005": "no objects found matching operation path",
"91004": "Presence auto-reenter failed",
"91005": "Presence state out of sync",
"91100": "Member implicitly left presence channel",
"92000": "LiveObjects validation error",
"92001": "Conflicting Error Code Usage",
"92002": "Cipher algorithm mismatch",
"92003": "Cipher decryption failed",
"92004": "Dual Purpose Cipher or Object Error",
"92005": "Duplicate context error",
"92006": "unable to perform operation without objectId or path",
"92007": "operation not processable on path",

"93001": "attempt to add an annotation listener without having requested the annotation_subscribe channel mode in ChannelOptions, which won't do anything (we only deliver annotations to clients who have explicitly requested them)",
"93002": "unable to perform operation; this operation can only be performed on channel in a namespace with Mutable Messages enabled",

"101000": "must have a non-empty name for the space",
"101001": "must enter a space to perform this operation",
"101002": "lock request already exists",
"101003": "lock is currently locked",
"101004": "lock was invalidated by a concurrent lock request which now holds the lock",

"92100": "Encoding value too long",
"93001": "Annotations channel state invalid",
"93002": "Mutable Messages feature required",
"100000": "Asset Tracking SDK error",
"100001": "Invalid Asset Tracking message format",
"100002": "Token fetch failed",
"100003": "Asset Tracking authentication failure",
"100004": "Subscriber never online",
"100005": "Subscriber not online",
"101000": "Space name missing",
"101001": "Not entered space",
"101002": "Lock request already exists",
"101003": "Lock is locked",
"101004": "Lock invalidated",
"102000": "chat room name is invalid",
"102001": "room attachment failed (messages)",
"102002": "room attachment failed (presence)",
Expand All @@ -227,13 +222,14 @@
"102052": "room detachment failed (reactions)",
"102053": "room detachment failed (occupancy)",
"102054": "room detachment failed (typing)",
"102100": "room discontinuity",
"102101": "unable to perform operation; room is in failed state",
"102102": "unable to perform operation; room is releasing",
"102103": "unable to perform operation; room is released",
"102100": "Room discontinuity",
"102101": "Room in failed state",
"102102": "Room is releasing",
"102103": "Room is released",
"102104": "unable to perform operation; existing attempt failed",
"102105": "unknown room lifecycle error",

"102106": "Room released before operation completed",
"102107": "Room invalid state",
"103000": "unable to publish push notification",
"103001": "unable to publish push notification, retries exhausted",
"103002": "unable to publish push notification, no recipient for direct publish",
Expand Down
Loading
Loading