Clarify next_batch behavior and possible error responses

Signed-off-by: Logan Devine <logan@zirco.dev>

content/client-server-api/_index.md

@@ -4237,6 +4237,19 @@ not have to perform extra round trips to query it.
 
 {{% http-api spec="client-server" api="mutual_rooms" %}}
 
+#### Server behaviour
+
+The server may decide that the response to this endpoint is too large, and only return a
+subset of the results. In this case, the server should populate the optional field `next_batch`
+with an [opaque identifier](/appendices/#opaque-identifiers). The client may then supply
+the identifier as the `from` query parameter in a subsequent request, along with the original
+`user_id`, to fetch the next batch of responses. This will continue until the server no longer
+inserts `next_batch`, meaning there are no further results.
+
+Batch tokens generated by this endpoint SHOULD be valid for at least 10 minutes, after which,
+tokens can expire. Expired tokens SHOULD be handled similar to invalid tokens, and return
+a 400 response.
+
 ## Modules
 
 Modules are parts of the Client-Server API which are not universal to

data/api/client-server/mutual_rooms.yaml

@@ -40,7 +40,10 @@ paths:
         - in: query
           name: from
           required: false
-          description: A pagination token from a previous result.
+          description: |-
+            A pagination token from a previous result. This should be a `next_batch` result from
+            a previous call to this endpoint. If not provided, the server will return the first
+            batch of results.
           example: next_batch_token
           schema:
             type: string
@@ -83,7 +86,9 @@ paths:
 
         "400":
           description: |-
-            The user ID provided was [non-compliant](/appendices/#historical-user-ids).
+            Part of the request was invalid. The `from` token provided was invalid or expired,
+            the `user_id` parameter was missing, [non-compliant](/appendices/#historical-user-ids),
+            or was the sender's own user ID.
           content:
             application/json:
               schema: