Key Takeaways
- MCP error handling for failed SMS is translating REST/DLR into isError + a safe message — not retry storms and not exploit PoCs.
- HTTP 200 accepted ≠ operator delivered. Webhooks and GET /messages own the rest.
- Timeouts and 5xx may retry with the same Idempotency-Key. 4xx validation and allowance-exhausted must fail closed.
- Do not leak Bearer tokens or OTP digits in tool error strings.
- You bring airtime. Free/Developer pause at the platform SMS cap.
MCP Server for Android SMS Gateway: MCP error handling for failed SMS — failure modes sits between the agent and POST /messages. Overview failures · Delivery reports. Live error shape: Developer Center. Spec: MCP.
Devices and send volume. You fund the SIM.
isError means stop. “Try louder” is how you duplicate OTP.
Map REST errors; do not swallow them
Illustrative error JSON (fields still follow Developer Center):
{
"error": {
"type": "invalid_request",
"code": "insufficient_credits",
"message": "The account does not have enough credits for this send."
},
"requestId": "req_01K2F8QW3N4RXB7M"
}Catch-all “SMS failed, retrying…” is how agents spend prepaid. Name the class: auth, validation, radio, cap.
Failed SMS failure table
| Signal | MCP should | Must not |
|---|---|---|
| Timeout / 502 | Uncertain + same Idempotency-Key | Mint a new key |
| 401 / 403 | isError, fix env | Print the Bearer token |
| 4xx validation | isError with field hint | Retry the same body forever |
| Allowance exhausted | isError, upgrade path | Invent overage billing |
| DLR failed | Terminal fail after webhook | Call it MCP host crash |
| Doze / last-seen | Ops, not JSON | Tight loop overnight |
Accepted is not delivered
Return the gateway message id. Let a DLR tool or webhook close the loop. create_webhook failures.
Retry without a new idempotency key
Same lesson as Laravel jobs. Retry policies. OTP: isolate the radio.
What the model should see
Status class + message id. Never the six digits, never the raw key. Logging and audit. On Free and Developer, sending pauses when you use the plan SMS allowance rather than silently billing aggregator-style overage. Upgrade or request a custom allowance to continue.
Next steps
Force a staging 4xx and a timeout; confirm isError vs uncertain. Install the app. 300 lifetime SMS is for those two canaries, not a retry hammer.
Related product pages
Jump to the live product docs for this topic—not another long-form article.
- SMS API documentationLive endpoint reference
- device and SMS volume pricingPlans and allowances
- Android SMS gateway product guideDefinition, product, and how to buy
- download the Android gateway appGet the APK
