Skip to content

docs: retry strategies uptime monitors can use per plan - #814

Merged
hlenke merged 4 commits into
mainfrom
docs/uptime-retry-plan-limits
Nov 11, 2026
Merged

hlenke merged 4 commits into
mainfrom
docs/uptime-retry-plan-limits

Conversation

@hlenke

@hlenke hlenke commented Nov 8, 2026 •

Copy link
Copy Markdown
Member

What changed and why

People ask why a retry strategy is rejected for URL, TCP, DNS or ICMP monitors, which strategies their plan allows, and why the error says "unlimited" when they only set one retry. The docs only said that some strategies "aren't available on every plan".

  • communicate/alerts/retries.mdx: new section "Retries on uptime monitors":
    • which strategies uptime monitors can use per plan (Hobby, Starter and Team: None and Single; Enterprise: all five), and that API checks aren't limited and heartbeat monitors don't retry;
    • that Fixed, Linear and Exponential count as multiple retries even with a maximum of 1;
    • what the web app shows, the API status and message, and that npx checkly deploy --preview reports it;
    • that monitors which already use such a strategy keep running but can't be updated until switched;
    • how group retry overrides and a project-level checks.retryStrategy interact with uptime monitors, and how to fix it.
  • constructs/retry-strategy.mdx: a note under "Default retry strategy" with the same limits for constructs (project default, CheckGroupV2 precedence), plus a UrlMonitor example with singleRetry().
  • URL monitor configuration: the existing note said "Most plans offer None and Single only". It now names the plans and links to the new section.
  • TCP, DNS, ICMP, SSL, gRPC and traceroute configuration pages: the existing "depends on your plan" line now names the plans and links to the new section.
  • platform/groups.mdx: in "Mixing checks and monitors in a group", one paragraph with retries as the example, linking to the new section.
  • Follow-up: a Trial row in the plan table, the Terraform error, and that monitors keeping a Fixed/Linear/Exponential strategy still retry with it.

Existing text isn't restyled. The new heading is sentence case (#774 restyles headings on these pages and doesn't touch these lines).

How each claim was verified

Tested on a local stack from monorepo main (e086a77755): real public API, web app and Checkly CLI 10.0.0 (checkly deploy against the local API). The plan fixture accounts came from the black-box seed: Hobby, Starter, Team, and Enterprise (CONTRACT plan type, shown as "Enterprise" in the app).

Plan setup:

  • Starter and Team get their entitlements from Stripe: the entitlement webhook writes the product's feature list to the account (handle-entitlement-update.ts). Locally I wrote each product's FEATURES list (billing-ng/products/starter-plan.ts, team-plan.ts) to the fixture accounts the same way.
  • Hobby and Enterprise come from the plan-type overrides (plan-overrides.ts).
  • The public API and CLI enforcing flags are set the way the 2025-12 migrations set them for every plan except Enterprise. Enterprise accounts are entitled to every strategy either way.
Claim How verified
Hobby, Starter, Team: uptime monitors accept None and Single only API: create and update for URL, TCP, DNS, ICMP, SSL, gRPC and traceroute with none, single, fixed, fixed with maxRetries: 1, linear and exponential. None/Single → 201/200; the rest → 402 on every plan
Enterprise: all five strategies Same matrix on the Enterprise fixture: all 201/200
API checks aren't limited Same matrix for API checks on Hobby, Starter and Team: all 201/200
Heartbeat monitors ignore a retry strategy API: heartbeat create and update with each strategy on every plan → 201/200, stored retryStrategy is null (DB)
Fixed etc. need Enterprise even with max retries 1 API: FIXED with maxRetries: 1 → 402
Exact message and 402 Payment Required API response body, identical for every rejected case
Web app greys out Fixed/Linear/Exponential (URL, TCP, DNS, ICMP, gRPC) Web app, Team account: new-monitor forms for all five types have those options disabled. "Single" is preselected
Existing monitor with such a strategy: message shown, can't save until None or Single Web app: monitor given a Linear/Fixed strategy in SQL shows the message, and Save is disabled ("Some required fields are empty or have errors"). Picking Single and saving works (DB)
Such monitors keep running Monitor with FIXED set in SQL on a Team account: the scheduler daemon still scheduled its runs ("SchedulerDaemon: scheduling check")
Every update to such a monitor is rejected, even rename or deactivate API PUT that renames it (with or without retryStrategy in the body) → 402; PUT with only activated: false → 402; PUT with SINGLE_RETRY → 200
npx checkly deploy fails with the message; --preview reports it CLI against the local API: deploy --preview and deploy both print [logical-id] <message>; a monitor with singleRetry() deploys
Group override applies to uptime monitors; can't set Fixed/Linear/Exponential on a group with an uptime monitor API: v2 group holding a URL monitor, update to FIXED → 402 "CheckGroup update failed due to: …" with the monitor in validationErrors. Update to SINGLE_RETRY, null or FALLBACK → 200. A group with only an API check → FIXED 200. Web app: group "Retries & Alerting" tab shows the quoted message and it clears on Single
Can't add an uptime monitor to such a group API: create a URL or TCP monitor in a v1 group with FIXED → 402 (also with the monitor's own SINGLE/none); move a URL monitor into a FIXED group → 402; API check in that group → 201
"Group override for retries" label Web app group form
Project-level checks.retryStrategy applies to monitors without their own CLI: linear project default + monitor without retryStrategy → deploy fails; same with singleRetry() on the monitor → deploys
A group's retryStrategy takes precedence over the monitor's; noRetries()/singleRetry() on the group work CLI: CheckGroupV2 with linearStrategy + monitor with singleRetry() → deploy fails; group with singleRetry() or noRetries() → deploys
Trial: uptime monitors accept None and Single only; API checks every strategy API on a Trial fixture set up as signup does (plan trial-02, its features): URL, TCP, DNS, ICMP with none/single → 201, fixed, fixed with maxRetries: 1, linear, exponential → 402 with the same message; API check: all 201
Terraform: terraform apply fails with unexpected response status 402: and the API body; terraform plan doesn't report it Checkly provider v1.32.0 (latest release) run with OpenTofu 1.13.2 against the local API, Hobby fixture: checkly_url_monitor with FIXED → plan OK, apply Error: API error 1: unexpected response status 402: "{…\"message\":\"The unlimited retry strategy isn’t supported on your plan. …\"}"; changing an existing monitor from SINGLE_RETRY to FIXED → Error: API error 3: Couldn't update check, Error: unexpected response status 402: …
A monitor that keeps such a strategy still retries with it URL monitor created with FIXED (2 retries, 10 s) on the Enterprise fixture, then the account moved to Hobby (plan hobby-01; a new FIXED monitor now → 402). Target returning 500, real runs through scheduler → go-runner → results daemon: before and after the move, each failing run made 3 attempts (2 ATTEMPT + 1 FINAL results, about 11 s apart)
Construct snippet Deployed as-is with the CLI; npm run check:snippets passes

Docs checks (frontmatter, anchors, links, redirects, sitemap, mint broken-links) pass. I rendered the changed sections with mint dev.

Not tested or left out

  • Legacy plans (Prepaid, Pay as you go, Deprecated) are left out of the table on purpose.
  • Web app forms for traceroute monitors don't grey out the options a plan lacks (the API still rejects them on save), so the web app bullet names only the URL, TCP, DNS, ICMP and gRPC forms.
  • Terraform was run with OpenTofu, which prints the provider's error the same way; the Terraform CLI itself wasn't installed.
  • Some other points were left out pending product decisions.

🤖 Generated with Claude Code

Add "Retries on uptime monitors" to the retries page: None and Single on Hobby, Starter and Team, all strategies on Enterprise, the 402 message and what "unlimited" means, monitors that already use a strategy the plan lacks, group overrides and project-level defaults. Point the uptime monitor configuration pages, the groups page and the retry strategy construct to it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mintlify

mintlify Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
checkly-422f444a 🟢 Ready View Preview Nov 11, 2026, 3:05 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

Add a Trial row to the uptime monitor retry table, what the Terraform
provider prints for a strategy the plan doesn't include, and that
monitors keeping such a strategy still retry with it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@hlenke hlenke left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ready to merge · The per-plan retry limits, the error message and the UI labels all match the entitlement and webapp source. What's left is optional wording and consistency.

CI passes, it's mergeable, and main hasn't changed any of the 10 files since the merge base. The new ### Retries on uptime monitors section sits at the end of "Check retry strategies", after "Network retries". That placement works.

Overlap: #812 also edits platform/groups.mdx, but in a different hunk (it adds a Warning under "Retries & Alerting"; this PR adds a paragraph to "Mixing Checks and Monitors in a Group"). They don't conflict and can land in either order.

Optional consistency items (not on diff lines):

  • Trials: the new table says trials are limited to None and Single (correct: the trial plan gets the Team feature set). Every other new mention says only "the Hobby, Starter and Team plans": the six configuration.mdx bullets, the URL monitor Note, retries.mdx:112, the constructs/retry-strategy.mdx Note and platform/groups.mdx. A trial user reading one of those could assume the limit doesn't apply to them. Consider "the Hobby, Starter and Team plans and trials" in those places.
  • Missed siblings: detect/uptime-monitoring/tcp-monitors/quickstart.mdx:71 and detect/uptime-monitoring/url-monitors/quickstart.mdx:67 still have the old "Which retry strategies you can use depends on your plan." bullet that this PR updates on the configuration pages. Give them the same sentence and link.
  • Construct Note length: the <Note> on constructs/retry-strategy.mdx (lines 77–96) holds a paragraph, a list and a code block. The editing rules keep callouts short. A #### Retry strategies for monitors subsection under "Default retry strategy" would carry the same content without the callout box.

Inline: 0 blockers, 0 important, 2 wording (optional).

What I checked
  • Read the whole diff from merge base e0e0277f, all 10 files. Read communicate/alerts/retries.mdx and constructs/retry-strategy.mdx in full at the PR head, including their heading outlines.
  • gh pr checks 814: all pass. gh pr view: MERGEABLE / CLEAN. git log e0e0277f..origin/main: nothing new on main.
  • Siblings: all six uptime-monitor configuration.mdx bullets (DNS, gRPC, ICMP, SSL, TCP, traceroute) get the same sentence, and the URL monitor Note is reworded to match. git grep across *.mdx found the two quickstart bullets listed above still on the old wording. No construct page for a monitor states plan limits for retries.
  • Plan matrix: monorepo origin/main@84921d2637, apps/backend/api/src/common/services/entitlements/. The Hobby override grants uptime no-retry and single-retry only. Starter and Team products (billing-ng/products/starter-plan.ts, team-plan.ts) list the same two. The trial override takes the Team product's features. The multiple-retries entitlement is granted only by the Contract (Enterprise) override and is listed as Enterprise-only in lib/product-catalog.ts. API-check retry entitlements for Fixed, Linear and Exponential are granted on Hobby, Starter and Team. This matches the table and line 93.
  • Error message: the enforcement rule for uptime retry strategies (enforcement-engine/rules/110-uptime-retry-strategy.ts) skips heartbeat monitors. It treats any strategy other than none and single as the multiple-retries entitlement, whatever maxRetries is, which matches line 95 and line 106. It builds the message from the note in lib/plan-limits/notes.ts plus "Your plan supports no retries (retryStrategy: null) or a single retry (SINGLE_RETRY)." The quoted block on line 103 is exact.
  • UI strings: apps/webapp/src/components/retries/ResourceRetrySettings.i18n.ts has "This retry strategy is not available on your current plan. Adjust setting or upgrade.", the group validation message quoted on line 114, and the option labels None, Single, Fixed, Linear and Exponential. "Group override for retries" is OverrideByGroupCheckbox with section title "Retries".
  • Construct snippet: checkly-cli origin/main@a655b42f, packages/cli/src/constructs/retry-strategy.ts. singleRetry() accepts baseBackoffSeconds, and noRetries() exists. UrlMonitor takes request.url.
  • pr_impact.py: only info notes that /communicate/alerts/retries and /constructs/retry-strategy are hub pages. The PR changes no slugs or anchors.
  • Anchors resolve: #retries-on-uptime-monitors, /constructs/retry-strategy#default-retry-strategy and /platform/groups#mixing-checks-and-monitors-in-a-group.
  • Could not verify from source: which web app monitor forms grey out the options (the PR names five types and leaves out SSL and traceroute); that an update which only renames or deactivates a monitor is rejected; that monitors keep retrying with an existing multi-retry strategy after a downgrade; and the Terraform output. The PR author reports testing each of these end to end. I found nothing in source that contradicts them.
  • Local app unavailable (BUSY), so I verified against source.

Comment thread communicate/alerts/retries.mdx Resolved
Comment thread communicate/alerts/retries.mdx Resolved
@hlenke
hlenke enabled auto-merge (squash) November 11, 2026 03:05
@hlenke
hlenke merged commit ea33842 into main Nov 11, 2026
7 checks passed
@hlenke
hlenke deleted the docs/uptime-retry-plan-limits branch November 11, 2026 03:09

This branch was successfully deployed

1 active deployment
staging — 6cad726e Deployed Nov 11, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant