Maintenance Mode
Maintenance mode freezes a single tenant during planned maintenance. While it is
active, every one of that tenant's web and API requests returns HTTP 503 until
you turn it back off. Use it for work that must not run against live traffic —
database migrations, a data backfill, or any change where in-flight requests
would see an inconsistent state.
Maintenance mode is scoped to one tenant. Putting one organization into maintenance has no effect on any other tenant, and the landlord dashboard itself is never affected — so the dashboard you use to turn maintenance off stays reachable the whole time.
Enabling maintenance mode
Maintenance mode is a per-tenant feature flag, toggled from the landlord dashboard:
- Open Tenants and select the tenant you want to freeze.
- Switch to the Features tab.
- Toggle Maintenance mode on.
The change applies immediately — there is no deploy or cache-clear step. Turn the toggle off from the same screen to restore normal traffic.
Managing a tenant's feature flags from the landlord dashboard requires super-admin access.
What visitors and integrations see
While the flag is on, the tenant behaves as follows:
| Surface | Behavior |
|---|---|
| Tenant web pages | Return HTTP 503 Service Unavailable. |
| Tenant API (REST and session) | Return HTTP 503 Service Unavailable. |
503 responses | Include a Retry-After: 120 header so clients know to try again. |
| Landlord dashboard | Unaffected — remains reachable so you can turn maintenance off. |
Because both the REST and session APIs return 503, embedded SDK components and
any external integrations that call the tenant will pause rather than act on
partial data. The Retry-After header lets well-behaved clients and monitors
back off and retry automatically once maintenance ends.
Maintenance mode is a hard stop, not a read-only mode. Enable it only for as long as the underlying work takes, and confirm the toggle is off before considering the maintenance window closed.
Related
- Feature Flags — how platform-wide and per-tenant flags work.
- Health Checks — monitor a tenant's queues before and after a maintenance window.