From dd6af5bfb14ef4f385d1b2cc9d960042a2a7124e Mon Sep 17 00:00:00 2001
From: Eric Eastwood <madlittlemods@gmail.com>
Date: Wed, 31 May 2023 04:50:21 -0500
Subject: [PATCH] Document why `/state_ids` can respond with a 404 (#1521)

---
 .../server_server/newsfragments/1521.clarification    |  1 +
 data/api/server-server/events.yaml                    | 11 +++++++++++
 2 files changed, 12 insertions(+)
 create mode 100644 changelogs/server_server/newsfragments/1521.clarification

diff --git a/changelogs/server_server/newsfragments/1521.clarification b/changelogs/server_server/newsfragments/1521.clarification
new file mode 100644
index 00000000..6c1ebf9d
--- /dev/null
+++ b/changelogs/server_server/newsfragments/1521.clarification
@@ -0,0 +1 @@
+Document why `/state_ids` can respond with a 404.
diff --git a/data/api/server-server/events.yaml b/data/api/server-server/events.yaml
index 427978fb..6d7ca45a 100644
--- a/data/api/server-server/events.yaml
+++ b/data/api/server-server/events.yaml
@@ -137,6 +137,17 @@ paths:
                   type: string
                 example: ["$an_event:example.org"]
             required: ['auth_chain_ids', 'pdu_ids']
+        404:
+          description: |-
+            The given `event_id` was not found or the server doesn't know about the state at
+            that event to return anything useful.
+          examples:
+            application/json: {
+                "errcode": "M_NOT_FOUND",
+                "error": "Could not find event $Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg"
+              }
+          schema:
+            "$ref": "../client-server/definitions/errors/error.yaml"
   "/event/{eventId}":
     get:
       summary: Get a single event