Key Takeaways
- MCP error handling for failed SMS means classifying HTTP, queue, radio, and carrier failures — then returning structured tool errors.
- A 200 from the control plane is accept/queue, not guaranteed handset delivery. Use GET message + webhooks for truth.
- Retries need Idempotency-Key and backoff. Blind agent retries burn operator airtime.
- Surface safe codes/messages to the model; keep raw secrets and full OTP bodies out of transcripts.
- You bring Android + carrier credit. Platform pricing is devices plus send volume.
Teams land on mcp error handling for failed sms after an agent reports “success” while the handset never sent. This setup walkthrough wires classification into your MCP wrapper. Concepts: error handling concepts. DLR: delivery reports. Docs: SMS API documentation.
You need a working Android phone with a SIM and SMS credit from your mobile operator. Operator message costs are yours—we do not sell carrier SMS balance. Service pricing is based on device count and total SMS sent through the gateway.
Failure layers
MCP hosts only see what your tool returns. If you collapse every problem into “failed”, agents thrash. Split: auth/validation (fix the request), control-plane accept (queued), device offline (ops), carrier reject (content/MSISDN/credit). Failure-modes spoke: error handling failure modes.
Tool OK means the wrapper spoke HTTPS correctly. Delivered means the radio and operator said so — usually via DLR or webhook, not the first tool return.
Map errors for agents
| Signal | Likely layer | Agent-safe next step |
|---|---|---|
| 401 / 403 | Auth / scope | Stop; alert human; do not retry loops |
| 4xx validation | Client input | Fix to/text; no airtime burn |
| Accepted, device offline | Ops / radio | list_devices; wait or route deviceIds |
| message.failed webhook | Carrier / handset | Policy-based retry with new Idempotency-Key only if allowed |
| Timeout in host | MCP transport | Check job id; do not double-send OTP |
Setup walkthrough
- Send via REST with intentional bad auth and bad MSISDN; capture status bodies from OpenAPI.
- In the MCP server, map those statuses into structured tool errors (code, retryable, human message).
- On success responses, return message id — not “delivered”.
- Add a get_status tool or document that agents must wait on webhooks (create webhook setup).
- Test offline phone: unplug data, send, confirm the tool explains queue/offline rather than inventing success.
Retry rules
Put retry policy in code: max attempts, backoff, Idempotency-Key reuse rules for the same logical send. OTP lanes should prefer user-driven resend over agent loops. Rate/safety: MCP rate limits and safety.
Observe DLR + webhooks
Dashboard history and webhooks are the audit trail when an agent argues with support. Keep message ids in your app DB. Feature: multi-device routing helps when one radio is the failure — listing devices is the read path (list_devices setup).
Next steps
Canary staff numbers, then enable write tools. Pricing: devices and SMS volume. Do not brand error-handling docs as Unlimited SMS — plan caps and carrier fair-use still apply.
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
- device setup guidePair and go live
- download the Android gateway appGet the APK
