Maintenance mode
Use the Maintenance mode section of System → Config to set a window and message for a migration or cutover; the old Maintenance address redirects there. Enabling maintenance does not run database migrations for you.
Behavior
Section titled “Behavior”| Target | Behavior |
|---|---|
| New model, tool, MCP and realtime requests | 503 with maintenance and retry headers; rejected before authentication, without request logs, charges or RPM consumption |
| Health and read-only model, quota and catalog interfaces | Remain available; /health returns 200 with maintenance state |
| Existing streams | Continue and settle normally |
| Admin writes | Optional freeze, enabled by default, with necessary exceptions such as maintenance controls |

Run a window
Section titled “Run a window”- Set the expected duration (a positive whole number of minutes) and localized messages, preview what clients will see, and decide whether to freeze Admin writes. The duration is only a hint; maintenance never ends automatically.
- Enable and verify the banner and new-request response. Per-process caches introduce a short propagation delay. While maintenance is active, the same section shows the expected recovery time and lets you extend or end it.
- Wait for in-flight work before applying the migration or cutover instructions.
- Disable maintenance on the environment actually receiving traffic, then make a real test call.
Configuration read failures allow traffic. Maintenance mode does not replace enforced database or network isolation. Database cutovers may copy maintenance state, so check it explicitly after switching.
See the maintenance reference for exceptions, permissions and runtime details.