Skip to content

docs(alerts): SMS and phone call quotas, test limits and failed alerts - #815

Merged
hlenke merged 6 commits into
mainfrom
docs/sms-phone-quota-limits
Nov 11, 2026
Merged

hlenke merged 6 commits into
mainfrom
docs/sms-phone-quota-limits

Conversation

@hlenke

@hlenke hlenke commented Nov 8, 2026 •

Copy link
Copy Markdown
Member

What changed and why

The SMS and phone call pages said that sends count against a monthly quota and pointed to the pricing page, but didn't say what happens when the quota runs out, where to see it, how test messages behave, or why a phone call channel on Starter never calls. This PR adds that, and corrects one existing claim.

integrations/alerts/sms.mdx

  • A table of the messages the channel form and the API show when a number is rejected (format, unsupported country, paid-only country on a trial, Hobby plan), with what to do.
  • Monthly SMS quota: shared by all SMS channels in the account, starts again each calendar month, test messages don't count, and what an alert looks like in the alert notification log once the quota is used (Failed, Account hit the monthly SMS limit). Quota numbers stay on the pricing page.
  • Test messages: the Test alert channel button, and the daily test limit on trial and Hobby accounts (the button shows a wait time; the API answers 429 with Alert channel test rate limit exceeded).
  • Troubleshooting a missing SMS alert: filter the notification log and read the notification result. Lists each specific failure result with a fix.
  • The test limit resets after 24 hours, and a line to contact support for more SMS or phone calls.
  • On every plan, at most two tests a minute across all alert channel types (also on the phone call page).

integrations/alerts/phone-calls.mdx

  • Corrected: "Phone call channels aren't available on the Hobby and Starter plans". Starter accounts can create and test a phone call channel (web app and API), but their call alerts fail with Account hit the monthly CALL limit because Starter includes no phone calls. Hobby accounts can't create the channel.
  • The paid-only countries are the same as for SMS, with a link to the SMS table and the call-specific web app message.
  • Monthly phone call quota: same model as SMS, with Account hit the monthly CALL limit, and the daily test-call limit on trials, which resets after 24 hours. A line to contact support for more.
  • New Troubleshooting a missing phone call alert: the failure results for calls with a fix for each.

Only the body text changes; the frontmatter lines that #774 touches are untouched. No overlap with #811 (Slack) or #812 (alerts overview).

How each claim was verified

Local stack at monorepo origin/main (e086a77755): API, results and alerting daemons, go-runner, web app. Plan fixture accounts (Hobby, Starter, Team, Trial, Contract) seeded by the devenv; real API check runs triggered real alerts.

Claim How it was verified
Hobby can't create SMS or phone call channels API POST (public and internal) → 402 Adding or changing SMS and phone call alert channels requires the Starter plan or above.; web app shows both tiles disabled with a Starter badge
Starter can create a phone call channel API 201/200; web app opens and offers the phone call form with Test alert channel
Starter phone call alerts aren't sent Real failing check on the Starter fixture with a phone call and an SMS channel: call notification FAILURE, Account hit the monthly CALL limit; SMS was attempted. Starter's 0-call allowance is on the public pricing page
Phone call alerts on Team and above Public pricing page (Team and Enterprise include phone calls)
Number rejection messages (web app and API) API: +49 151 … and +49-151-… and over-long numbers → phoneNumber is not a valid phone number; 0049…, 49… (no +) and +7… → Invalid country code…. Web app: same inputs show The number field must be a valid phone number and Invalid country code…
Paid-only countries on trials (SMS and calls) Trial fixture, Brazil number: API 402 with the paid-plan message for SMS and CALL; web app shows SMS to this country requires a paid plan… and Calls to this country require a paid plan…. Team fixture: same number accepted
Quota shared per account, per calendar month DB: usage is one row per account, channel, month and year. With the previous month over the limit and no row for this month, a new alert was sent and counted on a new current-month row
At the limit, alerts fail with the limit message Usage set to the quota in the DB, real alert → SMS and CALL notifications FAILURE with Account hit the monthly SMS limit / …CALL limit; shown in the web app notification log as Delivery status: Failed and Notification result
Below the limit, alerts are sent and counted Usage set to quota − 1 → no limit message, usage incremented by 1 per channel
Test messages don't count against the quota Usage unchanged after test sends on every fixture; a test SMS at the limit still went to the provider
Test limit on trial and Hobby API: Hobby and Trial fixtures 429 Alert channel test rate limit exceeded after the allowance, for SMS and CALL; Starter and Team not limited by it. Web app (trial): after the allowance the button turns into Wait …s, for SMS and phone calls
Notification log filter and fields Web app: channel filter, Show failures only, failed notification detail
The test limit resets after 24 hours API on the Hobby/Trial fixtures: after the allowance, 429 with a Retry-After of about 24 hours; config: refill interval 86_400_000 ms (alertChannelTestBucketRefillIntervalMs, monorepo origin/main 796988bcda)
SMS failure results: Invalid phone number, Phone number doesn't support SMS, Region not enabled, Attempt to send to unsubscribed recipient, Incomplete alert channel config, FROM number not associated with Twilio account, Failed to send the SMS Code only: exact strings from SmsAlertChannel.ts (handleSmsError, sendAlert) on origin/main 796988bcda. Meanings and fixes from the provider's public error pages for the mapped codes (21211, 21614, 21408, 21610: opt back in by texting START)
Call failure results: Incomplete alert channel config, Failed to send the Call Code only: channels/call/index.ts sendCallAlert on origin/main; calls have no more specific alert results
More SMS or phone calls: contact support Product decision; no promise on price or approval
At most two tests a minute on every plan; the third fails with Test rate limit exceeded Real account on the Enterprise plan (production), webhook channel, Test alert channel clicked 4 times within about 10 s: POST /accounts/{id}/alert-channels/test → 200, 200, 429, 429; toast Test rate limit exceeded, response Rate limit exceeded. A test 65 s later → 200
The per-minute limit covers all channel types Code: one route-level limiter on the test endpoint (alert-channels/routes.ts, alertChannelTestRequests 2 per alertChannelTestDuration 60 s, origin/main 796988bcda), keyed by user, not by channel type. Tested with a webhook channel only

Not tested, or left out

  • Actual SMS and call delivery: our SMS and call provider can't run locally, so the specific failure results are code-verified only (exact strings from origin/main).
  • The exact number of test messages a day: left out by decision.
  • Quota numbers stay on the pricing page. Quota warning emails are left out pending a product fix.
  • Whether the monthly quota follows the UTC calendar month: the meter keys on the database's now(), and the production database time zone isn't set in code (RDS is managed outside Terraform). Left at "calendar month".

🤖 Generated with Claude Code

…ed alerts

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, 2:02 AM

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

…re quota

Lists the specific notification results for failed SMS and phone call
alerts with a fix for each, says the trial/Hobby test limit resets after
24 hours, and adds a contact-support line for more SMS or calls.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Tested on an Enterprise account: the third test within a minute returns 429
and the web app shows 'Test rate limit exceeded'; a test after 60 s passes.

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.

Needs changes · All claims check out against source and the pricing page. Move the new rejection-messages table on the SMS page below the country list, which it now splits from its lead sentence.

The content is accurate: every message string, quota result, and test limit matches the backend and webapp source, and the corrected Starter claim on the phone call page is right. One layout fix and two optional wording fixes are inline.

CI passes, it's mergeable, and main hasn't changed either file since the merge base. No other open PR touches these two pages.

Sibling consistency (optional): the SMS page gets its own ## Test messages section. The phone call page puts the same test-limit text in the last paragraph of ## Monthly phone call quota. Consider giving the phone call page a matching ## Test calls section, so readers find the test limit in the same place on both pages.

Inline: 0 blockers, 1 important, 2 wording.

What I checked
  • Read the whole diff from merge base e0e0277f: integrations/alerts/sms.mdx (+34) and integrations/alerts/phone-calls.mdx (+21/-1). Read both pages in full at the PR head, including their heading outlines.
  • gh pr checks 815: all pass. gh pr view: MERGEABLE / CLEAN. git log e0e0277f..origin/main: nothing new on main.
  • pr_impact.py: no findings.
  • git grep on main for other pages that state phone call plan availability: only phone-calls.mdx:20, which this PR corrects.
  • Pricing: https://www.checklyhq.com/pricing/ lists phone alerts as Hobby 0, Starter 0, Team 200/month and Enterprise custom, and SMS as Hobby 0, Starter 100/month and Team 200/month. This supports "Phone call alerts are included on the Team plan and above" and the Starter behavior.
  • Quota results: monorepo apps/backend/api/src/common/services/alert-notification-service/AlertNotificationService.ts (origin/main@84921d2637). SMS and call sends check the account's monthly metered amount and fail each channel's notification with Account hit the monthly SMS limit / Account hit the monthly CALL limit. A missing quota counts as 0, so Starter calls fail. The metered amount grows by the number of channels.
  • SMS failure results: channels/sms/SmsAlertChannel.ts returns Region not enabled, Invalid phone number, Phone number doesn't support SMS, Attempt to send to unsubscribed recipient, FROM number not associated with Twilio account, Incomplete alert channel config and Failed to send the SMS. Call failure results: channels/call/index.ts returns Incomplete alert channel config and Failed to send the Call. InvocationResult.internalFailure stores the message as the result, so these strings are what the log shows.
  • Rejection messages: API: common/services/phone-number-checker.ts, decorators/authorization/policies/enforceAlertChannelCountryTier.ts and modules/public-api/projects/resources/alert-channel.ts. Web app: alert-channel-builder/channels/configs/sms/SmsConfig.vue and .../call/PhoneCallConfig.vue, which includes Calls to this country require a paid plan…. All strings match. The webapp's Invalid country code… message ends with a period; the table omits it, which is harmless.
  • Test limits: modules/alert-channels/run-test-helpers.ts applies a token bucket only to Hobby and trial accounts, only for SMS and CALL tests (plus email tests to several recipients), and answers 429 Alert channel test rate limit exceeded with Retry-After. modules/alert-channels/routes.ts and app-config/default.ts set a route limiter of 2 requests per 60 s on the test endpoint for all plans. The webapp toast title is Test rate limit exceeded (PageAlertChannelBuilder.vue).
  • Local app unavailable (BUSY), so I verified against source. I didn't rerun the PR author's local scenarios.

Comment thread integrations/alerts/sms.mdx Outdated
Comment on lines +26 to +33
When a number is rejected, the channel form or the API tells you why:

| Message | What to do |
| ------ | ------ |
| `The number field must be a valid phone number` (web app) or `phoneNumber is not a valid phone number` (API) | Enter the number in E.164 format: a `+`, the country code and the number, without spaces or dashes. |
| `Invalid country code. Please see our documentation for a full list of supported countries` | Start the number with `+` and the country code, and use a country from the table below. |
| `SMS to this country requires a paid plan. Upgrade your plan to use this number.` (web app) or `SMS and phone call alerts to this country are only available on a paid plan. Upgrade your plan to use this number.` (API) | The country is available on paid plans only, not on trials. |
| `Adding or changing SMS and phone call alert channels requires the Starter plan or above.` (API) | Your account is on the Hobby plan, which doesn't include SMS alerts. |

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.

Important: this table lands between "SMS alerts can only be sent to phone numbers in the following countries." (line 24) and the country table it introduces (line 35). The lead sentence now points at the wrong table, and the country list, which is what readers open this section for, moves down. Move lines 26–33 below the country table, before ## SMS alert number and sender ID. In the second row, change "use a country from the table below" to "the table above".

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.

correct. lets apply these changes

Comment thread integrations/alerts/phone-calls.mdx Resolved
Comment thread integrations/alerts/phone-calls.mdx Resolved
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@hlenke
hlenke merged commit e1ec468 into main Nov 11, 2026
7 checks passed
@hlenke
hlenke deleted the docs/sms-phone-quota-limits branch November 11, 2026 02:05

This branch was successfully deployed

1 active deployment
staging — 1da2531e 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