Maintenance Windows

Use this guide to configure scheduled maintenance windows for endpoints.

Purpose

This guide helps you:

• Schedule regular endpoint pauses for backend deployments or maintenance.
• Configure UTC cron expressions for recurring downtime.
• Understand how maintenance windows interact with manual pauses.

How maintenance windows work

Maintenance windows automatically disable an endpoint for a fixed duration on a recurring schedule. This is useful for:

• Regular backend deployment windows (e.g., every night at 3 AM for 30 minutes).
• Scheduled maintenance of downstream systems.
• Enforcing quiet periods for testing or data migration.

When a maintenance window is active:

• Inbound requests are rejected with HTTP 503 Service Unavailable.
• Outcome is logged as PAUSED (same as manual pause).
• The endpoint UI shows "Paused (maintenance window)".

Prerequisites and permissions

• Endpoint edit access.
• Understanding of cron syntax (examples provided below).

Step-by-step workflow

1. Enable maintenance windows

1. Open the endpoint edit page.
2. Navigate to the Details tab.
3. Scroll to the Maintenance windows section.
4. Enable Scheduled maintenance.

2. Configure the schedule

Cron format:

* * * * *
│ │ │ │ │
│ │ │ │ └── Day of week (0–6, Sunday=0)
│ │ │ └──── Month (1–12)
│ │ └────── Day of month (1–31)
│ └──────── Hour (0–23)
└────────── Minute (0–59)

3. Cron expression examples

All times are in UTC.

Cron expressions are validated at save time. Invalid patterns are rejected with 400 Bad Request.

4. Timezone

Maintenance windows are always evaluated in UTC. Convert your local schedule to UTC before entering the cron expression. UTC has no daylight-saving transitions, so window timing stays predictable year-round.

5. Understand manual-pause interaction

Maintenance windows never shorten an existing manual pause. If a manual pause would end later than the scheduled window, the later manual resume time is kept. If the maintenance window lasts longer, the endpoint remains paused until the maintenance window ends.

6. Monitor maintenance windows

In the endpoint details view:

• The "Next maintenance" timestamp shows when the next scheduled window begins.
• During an active window, the endpoint shows "Paused (maintenance window)" with the remaining duration.

In Request activity:

• Requests rejected during a maintenance window have outcome PAUSED.

Expected result and verification checks

• Maintenance windows fire on schedule in UTC.
• Inbound requests during the window are rejected with 503 and PAUSED outcome.
• After the duration expires, the endpoint automatically resumes.
• The "Next maintenance" UI updates after each window fires.

Common issues and fixes

• Window doesn't fire: Verify the cron expression and timezone. Use a cron validator (e.g., crontab.guru) to test the schedule.
• Duration too short: Increase the duration if the maintenance consistently exceeds the window.
• DST transition issues: Use UTC or choose a time not affected by daylight-saving transitions.
• Manual pause lasts longer than expected: Scheduled windows never shorten an existing manual pause. If you need to resume earlier, manually resume the endpoint.

Cron validation

PayloadRelay validates cron expressions at save time:

• Use standard 5-field cron (min hour dom mon dow); the API also accepts Spring 6-field cron with a leading seconds field.
• Each field must be valid (*, */n, n, n-m, n,m).
• Numeric ranges must be within bounds (e.g., hour 0–23).

Invalid expressions return 400 Bad Request with a descriptive error.

Related guides

• Endpoint Management
• Observability
• Troubleshooting