Troubleshooting

What you see, why it happens, how to fix it. Branch on error.code, not the message text. error.docs links to the matching entry.

The call never completes

You seerefused, DNS failure or a hang
Why it happens
There is no network route to m91-api.msg91.com, common in CI, containers and sandboxes.
Fix
Check curl -sS -o /dev/null -w '%{http_code}' https://m91-api.msg91.com/api/public/index.md prints 200. If you are an agent, say you could not verify and hand over the exact command.

401 on every request

You see"UNAUTHORIZED" "Invalid sender token"
Why it happens
The token is wrong, revoked, or the URL was assembled from parts (a trailing slash or a truncated copy).
Fix
Copy the link again from the app and use it as one string. A revoked link cannot be recovered.

A bare GET says ok but nothing rang

You see"ok":true
Why it happens
Not a failure. A link without title is a connection test, so previews and crawlers cannot wake a team.
Fix
Add ?title=… to raise an alert.

Rejected requests

400 VALIDATION_ERROR

You see"title is required" "Unknown field: " "must be one of: LOW, MEDIUM, HIGH, CRITICAL"
Why it happens
A field is wrong: missing or short title (5–2000), a typo or unknown field, lowercase severity, an effect other than SHARED/PERSONAL, a label over 24 characters, or too many options.
Fix
Read error.details.fields, which names the field. There is no recipient field.

400 MALFORMED_JSON, or an empty body

You see"MALFORMED_JSON"
Why it happens
Shell quoting, a missing Content-Type: application/json header, or PowerShell mangling curl.exe quoting.
Fix
Use -d @payload.json with the header. On PowerShell use Invoke-RestMethod (see Setting up).

413 PAYLOAD_TOO_LARGE

You see"PAYLOAD_TOO_LARGE"
Why it happens
The body is over 1 MB, usually a log in description.
Fix
Send a summary and a link instead.

Nobody was reached

409 CHANNEL_EMPTY

You see"CHANNEL_EMPTY" "Nobody has joined this channel yet"
Why it happens
Nobody who can receive alerts is in the channel. Invites are not accepted, or M91 is not installed. details.unregistered lists them.
Fix
People must install M91, sign in and accept. Check this first.

delivered is 0 or low

You see"delivered":0
Why it happens
Either a deduplicated send ("deduplicated":true is also present), or the roster: unregistered (never signed in), noDevice (signed in, no device, often after a reinstall), or invites not accepted.
Fix
Check deduplicated first, then ask people to open the M91 app once. Always assert on delivered, not the status code.

The phone stayed silent

You seea normal 201
Why it happens
delivered means sent, not heard. Notifications may be denied for M91, or the device token is stale.
Fix
Check notification permission and reopen the app. Only a response proves somebody saw it.

No phone call was made

Why it happens
The alert was LOW or MEDIUM, or HIGH and somebody opened it, or somebody responded, or that person was called recently, or the hourly call quota is spent.
Fix
Use CRITICAL when a call is always warranted.

Repeats and closing

deduplicated: true

You see"deduplicated":true
Why it happens
Working as intended. An alert with that customId is still open, or an identical message arrived within 5 seconds.
Fix
Close the first alert to raise a fresh one. For a different problem, use a different customId. In manual tests, change any field.

Alerts never repeat, or every repeat is new

You see"deduplicated":true forever, or a flood then 429
Why it happens
An alert was never closed, so repeats are absorbed. Or the customId has a timestamp or UUID in it, so nothing matches.
Fix
Use one stable name per problem (disk-full-node7) and close the alert when the problem clears. A worse problem needs its own customId.

429 RATE_LIMITED

You see"RATE_LIMITED"
Why it happens
More than 60 sends a minute on one link, usually no customId or a retry loop.
Fix
Honour Retry-After, add a customId, and close when clear.

404 or 403 on close

You see"alert_not_found" "FORBIDDEN"
Why it happens
Normal. Nothing was open with that id, or it was already resolved.
Fix
Treat both as success.

decision stays null

You see"decision":null
Why it happens
Nobody gave a SHARED answer. PERSONAL ones never become a decision, so “Seen” is never read as “Approved”.
Fix
Include a SHARED button and set your own timeout.

API key

401 on API-key calls, or state is null

You see"UNAUTHORIZED"
Why it happens
The key is missing, revoked, or sent without Bearer . A null state means you read it from the top level instead of data.
Fix
Send Authorization: Bearer m91sk_… and read body.data.state. GET /api/v1/me proves a key works.

404 not_a_recipient, or reachable: false

You see"not_a_recipient" "reachable": false
Why it happens
The number was never invited, or has not accepted. An alert never invites anyone, because consent comes first.
Fix
Invite with POST /recipients, then wait for them to accept in the app. Nothing in code can skip this.

A channel created by API key cannot be alerted by it

You seea 4xx when alerting that channel
Why it happens
Keys create channels and alert individuals. Alerting a channel is the send link’s job.
Fix
Use the sendLink returned by POST /api/v1/channels.

Looks like a bug, but is not

A SHARED answer did not close the alert

You seeit stays OPEN
Why it happens
By design. isAutoClose defaults to false. Closing says the problem is over, and usually only a person knows that.
Fix
Close it yourself, or send isAutoClose: true. With no buttons and no isAutoClose, nothing can ever close it.

Somebody wants to change their answer

You seethere is no endpoint
Why it happens
By design. One answer per person, and it is final.
Fix
Raise a new alert, or have them comment in the app.