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 pause 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.
• Rejected requests do not create request activity rows.
• The endpoint UI shows the standard paused state and resume countdown.

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 window section.
4. Enable Maintenance window.

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 the standard paused state with the remaining duration.

In Request activity:

• Requests rejected during a maintenance window are omitted. There is no request activity row or audit event for a scheduled pause; confirm it from the endpoint pause state, resume countdown, and "Next maintenance" timestamp.

Expected result and verification checks

• Maintenance windows fire on schedule in UTC.
• Inbound requests during the window are rejected with 503 and no request activity row.
• 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