errors: add client_id_too_long and annotation summary/deleted codes

errors/codes/40036.md

@@ -0,0 +1,18 @@
+---
+code: 40036
+identifier: client_id_too_long
+title: Client ID too long
+summary: A publish was rejected because the client ID of a message, presence message, object message or annotation exceeded the maximum permitted length. The client ID may have been set explicitly or inherited from the connection.
+---
+
+## What you should do
+
+Use a shorter client ID. Client IDs are limited to 100 bytes by default, which is far longer than any identifier needs to be; if you derive client IDs from longer values such as email addresses or token claims, use a fixed-length hash of the value instead.
+
+## Why it happens
+
+Every message, presence message, object message and annotation carries the client ID of its publisher, either set explicitly on the message or inherited from the client ID of the connection or request. Ably refuses to publish any whose client ID is longer than the limit.
+
+## What you'll see
+
+The error is reported with code 40036 and HTTP status 400. The message is of the form `clientId length (150 bytes) exceeds maximum of 100 bytes`.

errors/codes/93003.md

@@ -0,0 +1,18 @@
+---
+code: 93003
+identifier: annotation_summary_entry_limit_exceeded
+title: Annotation summary entry limit reached
+summary: An annotation was rejected because the message's annotation summary already held the maximum number of distinct combinations of annotation type, name and client ID. Annotations that would not add a new combination are still accepted.
+---
+
+## What you should do
+
+Nothing needs to change for annotations that update or remove an existing entry, such as a client deleting its reaction, which are always accepted. If messages in your app legitimately need summaries with more entries, contact Ably support to discuss raising the limit for your account.
+
+## Why it happens
+
+A message's [annotation summary](https://ably.com/docs/messages/annotations) records each distinct combination of annotation type, name and client ID, and is sent with every copy of the message, so its size is limited. Once the summary holds the maximum number of entries (1000 by default), an annotation that would add a new combination is refused. For example, once a message has reactions from the maximum number of distinct clients, a reaction from a new client is refused, but an existing client can still remove its reaction.
+
+## What you'll see
+
+The error is reported with code 93003 and HTTP status 400. The message is of the form `Unable to add annotation: the summary for message <serial> has reached the maximum of 1000 distinct (type, name, clientId) entries`.

errors/codes/93004.md

@@ -0,0 +1,18 @@
+---
+code: 93004
+identifier: annotation_target_message_deleted
+title: Annotation on a deleted message
+summary: An annotation was rejected because the message it referenced had been deleted. Annotations that remove an existing annotation from a deleted message are still accepted.
+---
+
+## What you should do
+
+Don't annotate messages that have been deleted. If a client may annotate a message around the time it is deleted, treat this error as meaning the message is gone.
+
+## Why it happens
+
+Once a message has been [deleted](https://ably.com/docs/messages/updates-deletes), new [annotations](https://ably.com/docs/messages/annotations) to it are refused. Deleting an existing annotation is still allowed, so clients can remove annotations they made before the message was deleted.
+
+## What you'll see
+
+The error is reported with code 93004 and HTTP status 400. The message is of the form `Unable to add annotation: message <serial> has been deleted`.

protocol/errors.json

@@ -172,6 +172,11 @@
       "title": "Integration filter regex not RE2-compatible",
       "summary": "An integration could not be configured because one of its filters, such as a channel filter or message filter, uses a regular expression that is not RE2-compatible. Backreferences and lookaround are not supported."
     },
+    "40036": {
+      "identifier": "client_id_too_long",
+      "title": "Client ID too long",
+      "summary": "A publish was rejected because the client ID of a message, presence message, object message or annotation exceeded the maximum permitted length. The client ID may have been set explicitly or inherited from the connection."
+    },
     "40099": {
       "identifier": "reserved_for_testing",
       "title": "Reserved for testing",
@@ -1122,6 +1127,16 @@
       "title": "Message annotations, updates, appends, and deletes not enabled",
       "summary": "An operation could not be performed because the channel did not have the 'Message annotations, updates, appends, and deletes' rule enabled."
     },
+    "93003": {
+      "identifier": "annotation_summary_entry_limit_exceeded",
+      "title": "Annotation summary entry limit reached",
+      "summary": "An annotation was rejected because the message's annotation summary already held the maximum number of distinct combinations of annotation type, name and client ID. Annotations that would not add a new combination are still accepted."
+    },
+    "93004": {
+      "identifier": "annotation_target_message_deleted",
+      "title": "Annotation on a deleted message",
+      "summary": "An annotation was rejected because the message it referenced had been deleted. Annotations that remove an existing annotation from a deleted message are still accepted."
+    },
     "101000": {
       "identifier": "space_name_is_empty",
       "title": "Space name is empty",