(/maintenance-mode) add details to errors (#1724)

Co-authored-by: victoria <[email protected]>
Co-authored-by: Alexis Aguilar <[email protected]>

Author: 3 people

docs/maintenance-mode.mdx

@@ -3,14 +3,36 @@ title: Maintenance Mode
 description: Learn about Clerk's Maintenance Mode.
 ---
 
-**Maintenance Mode** is a special operational state designed to ensure minimal disruption to signed-in users during critical database upgrades or outages.
+> [!IMPORTANT]
+> Maintenance mode will be deprecated in 2025 as we upgrade our infrastructure.
+
+Once or twice per year, Clerk undergoes maintenance on its infrastructure and enters **Maintenance Mode**. During this time, users who are already signed in will not be signed out, and will continue to have access to your app. However, new sign-ups, sign-ins and user mutations will return an error. **Maintenance Mode** is a special operational state designed to minimize disruption for signed-in users during critical database upgrades or outages.
 
 ## Production instances
 
-Mutation methods (`POST`, `PATCH`, `PUT`, `DELETE`) will be rejected with a `503 Service Unavailable` status, along with an error message informing users that the system is temporarily unavailable. This includes all sign-up and sign-in attempts. Clerk's prebuilt components and the hosted Account Portal will display errors for these requests.
+Mutation methods (`POST`, `PATCH`, `PUT`, `DELETE`) will be rejected with a `SystemUnderMaintenance` error. This includes all new sign-ups and sign-ins.
+
+Active sessions, and session refresh requests **are not** affected. This applies to `GET` requests as well as session refresh requests ([`/touch`](/docs/reference/frontend-api/tag/Sessions#operation/touchSession) and [`/tokens`](/docs/reference/frontend-api/tag/Sessions#operation/createSessionToken) endpoints). Users who are already signed in will not be signed out and will continue to have access to your app. However, any mutations to their user or org data will return the same `SystemUnderMaintenance` error.
+
+### API errors
+
+All mutations from both the Frontend API and the Backend API will return the following `SystemUnderMaintenance` error.
+
+```json
+// 503 StatusServiceUnavailable
+{
+  "shortMessage": "System under maintenance",
+  "longMessage": "We are currently undergoing maintenance and only essential operations are permitted. We will be back shortly.",
+  "code": "maintenance_mode"
+}
+```
+
+### UI components
+
+During **Maintenance Mode**, Clerk's UI components will display the following error for sign-ins, sign-ups, and all mutations to user and org data.
 
-GET requests, as well as session refresh requests ([`/touch`](/docs/reference/frontend-api/tag/Sessions#operation/touchSession) and [`/tokens`](/docs/reference/frontend-api/tag/Sessions#operation/createSessionToken) endpoints), aren't affected. Users with active sessions (already signed in) will not be signed out, and will continue to have access to your app. However, any mutations to their user or org data will return the same `503` error.
+![The \<SignIn /> component with a maintenance mode error.](/docs/images/maintenance-mode/maintenance-mode-error-sm.png)
 
 ## Development instances
 
-During this period, development instances will experience full downtime. Users will be unable to sign up or in, and already signed-in users will be signed out.
+For development instances, all requests will return a `SystemUnderMaintenance ` error, and the instance will be completely unavailable.