Maintenance windows
We occasionally take the platform down for planned work. During a window, every endpoint
answers 503 with the code maintenance:
Code
Code
detail carries the message written for the window and is meant to be shown to a person.
It is prose. Branch on code, not on it.
Windows are announced ahead of time on the status page, which is also where to confirm one has finished. You can subscribe there to be told when a window opens and closes rather than discovering it from a failed request.
Nothing you sent was applied
A blocked request is refused before it reaches any handler. It creates nothing, changes nothing, and consumes no credits, so there is no partial write to reconcile and no need to check whether something landed before you send it again.
Replay the whole request once the window ends. That holds for writes as much as reads:
a POST refused with maintenance is a POST that never happened.
Handle it
Treat maintenance as a signal to pause the integration, not as a per-request failure to
log and move past. Every subsequent call will fail the same way until the window closes,
so a queue that drops failures will drain itself into nothing.
Retry-After is how long to wait before trying again, in seconds. It is not how long the
window will last. Expect to be told maintenance more than once. Wait the interval out each time
rather than polling tightly; the answer will not change until the work is finished.
maintenance is a 503, but it is not service_unavailable. This one is planned and comes
with a Retry-After we chose deliberately; service_unavailable is an unplanned failure.
Check the status page first, and tell us if what you are
seeing is not on it. See errors.
What else stops
The window covers the whole platform, not only the API. Share links and public upload links are unavailable, and an embedded chat widget shows its unavailable state instead of starting a conversation. People signing in to the app reach a maintenance page carrying the same message rather than a half-working workspace.
A window applies to every workspace at once. It is a property of the platform, not something scheduled per customer.