From fa9dbbd3ecc261a4c77b2e522fef244b4a62f273 Mon Sep 17 00:00:00 2001
From: Paul Chobert <paul@chobert.fr>
Date: Fri, 11 Sep 2026 14:59:15 +0200
Subject: [PATCH] Stabilize the `M_UNKNOWN_DEVICE` error code (#20181)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Part of: #19415

TLDR: return the `M_UNKNOWN_DEVICE` error code instead of the unstable
`ORG.MATRIX.MSC4326.M_UNKNOWN_DEVICE` identifier.

> **[Added in `v1.17`]** Application services MAY similarly masquerade
as a specific device ID belonging the user ID through use of the
`device_id` query string parameter on the request. If the given device
ID is not known to belong to the user, the server will return a 400
`M_UNKNOWN_DEVICE` error.
>
> — [Matrix v1.19, Application Service API — Identity
assertion](https://spec.matrix.org/v1.19/application-service-api/#identity-assertion)

Synapse returns the correct 400, but with the unstable identifier.
MSC4326 was stabilized in Matrix 1.17 and its experimental flag was
already removed in #19033; only the error code identifier was left
behind.

Before:

```
GET /_matrix/client/v3/sync?user_id=@alice:test&device_id=NOT_A_REAL_DEVICE_ID  # appservice token
  400 {"errcode": "ORG.MATRIX.MSC4326.M_UNKNOWN_DEVICE"}
```

After:

```
GET /_matrix/client/v3/sync?user_id=@alice:test&device_id=NOT_A_REAL_DEVICE_ID  # appservice token
  400 {"errcode": "M_UNKNOWN_DEVICE"}
```

I verified that no implementation was currently handling the prefixed
error code.
---
 changelog.d/20181.bugfix | 1 +
 synapse/api/errors.py    | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)
 create mode 100644 changelog.d/20181.bugfix

diff --git a/changelog.d/20181.bugfix b/changelog.d/20181.bugfix
new file mode 100644
index 0000000000..477902b97f
--- /dev/null
+++ b/changelog.d/20181.bugfix
@@ -0,0 +1 @@
+Return the stable `M_UNKNOWN_DEVICE` error code, added in Matrix 1.17, instead of its unstable [MSC4326](https://github.com/matrix-org/matrix-spec-proposals/pull/4326)-prefixed identifier.
diff --git a/synapse/api/errors.py b/synapse/api/errors.py
index 038578dbed..75cf8add27 100644
--- a/synapse/api/errors.py
+++ b/synapse/api/errors.py
@@ -157,7 +157,7 @@ class Codes(str, Enum):
     MSC4306_NOT_IN_THREAD = "IO.ELEMENT.MSC4306.M_NOT_IN_THREAD"
 
     # Part of MSC4326
-    UNKNOWN_DEVICE = "ORG.MATRIX.MSC4326.M_UNKNOWN_DEVICE"
+    UNKNOWN_DEVICE = "M_UNKNOWN_DEVICE"
 
     USER_LIMIT_EXCEEDED = "M_USER_LIMIT_EXCEEDED"