api: Add REALM_DEACTIVATED error code.

In `validate_account_and_subdomain` we check
if user's realm is not deactivated. In case
of failure of this check, we raise our standard
JsonableError. While this works well in most
cases but it creates difficulties in handling
of users with deactivated realms for non-browser
clients.

So we register a new REALM_DEACTIVATED error
code so that clients can distinguish if error
is because of deactivated account. Following
these changes `validate_account_and_subdomain`
raises RealmDeactivatedError if user's realm
is deactivated.

This error is also documented in
`/api/rest-error-handling`.

Testing: I have mostly relied on automated
backend tests to test this.

Fixes #17763.

zerver/openapi/python_examples.py

@@ -1233,6 +1233,15 @@ def test_user_account_deactivated(client: Client) -> None:
     validate_against_openapi_schema(result, "/rest-error-handling", "post", "403_0")
 
 
+def test_realm_deactivated(client: Client) -> None:
+    request = {
+        "content": "**foo**",
+    }
+    result = client.render_message(request)
+
+    validate_against_openapi_schema(result, "/rest-error-handling", "post", "403_1")
+
+
 def test_invalid_stream_error(client: Client) -> None:
     result = client.get_stream_id("nonexistent")