errors: Add 40901 "Message sequence mismatch"

errors/codes/40901.md

@@ -0,0 +1,26 @@
+---
+code: 40901
+identifier: message_sequence_mismatch
+title: Message sequence mismatch
+summary: An update, delete or append was rejected because the sequence number it carried was not exactly one more than the message's current sequence number.
+---
+
+## What you should do
+
+Read the message's current sequence number from the error's `detail`, under `sequence`. Then publish the change again with that sequence number plus one.
+
+If the current sequence number is at or above the one you sent, your change may already have been applied. Read the latest version of the message before you send it again.
+
+If a series of appends failed part way through, the message is missing everything from the first failed append onwards. Publish an update with the full content instead, using the current sequence number plus one.
+
+If another client also changes the same message, your record of its sequence number no longer holds. Agree on who changes the message, or read its latest version before you change it.
+
+## Why it happens
+
+An update, delete or append can carry a sequence number in `version.sequence`. A message starts at sequence number 0 when it is created, and each change that carries a sequence number must be exactly one more than the current one. Changes are often sent without waiting for earlier ones to complete. When an earlier change fails, the next one arrives with a sequence number that is too high, and it is rejected so that the message never includes a later change without the earlier one. A change sent again arrives with a sequence number that is too low, and it is rejected so that it isn't applied twice.
+
+A change that carries no sequence number is not checked, and does not change the message's sequence number.
+
+## What you'll see
+
+The change is rejected and not applied. The error is reported with code 40901 and HTTP status 409, with a message of the form `message sequence <n> does not follow the current sequence <n>`. The message's current sequence number is in the error's `detail` under `sequence`.

protocol/errors.json

@@ -467,6 +467,11 @@
       "title": "Conflict",
       "summary": "The request conflicted with the current state of the target, so it could not be completed."
     },
+    "40901": {
+      "identifier": "message_sequence_mismatch",
+      "title": "Message sequence mismatch",
+      "summary": "An update, delete or append was rejected because the sequence number it carried was not exactly one more than the message's current sequence number."
+    },
     "41001": {
       "identifier": "push_device_registration_expired",
       "title": "Push device registration expired",