Key Takeaways
- MCP error handling for failed SMS: separate wrapper errors, HTTP 4xx/5xx, and radio/DLR failure — the agent should not retry all three the same way.
- Tool success is accept. Delivered is a later event.
- Not a first-party Cursor/Claude plugin. REST wrapper.
- Priced by devices and SMS send volume. You use your own phone and operator SMS credit. Failed radios still often spend operator credit.
- Free 300 SMS lifetime burns fast if the agent retries OTP.
- Confirm status shapes in Developer Center.
Concepts for MCP error handling for failed SMS stop the agent from double-texting a login code. Overview: MCP overview. Webhooks. MCP specification.
Priced by devices and SMS send volume. You use your own phone and operator SMS credit.
If every failure is
try send_sms again, you will bill the SIM twice and lock the user out of their own OTP.
Three failures that look the same in chat
Wrapper bug, API reject, radio miss. Docs: Developer Center.
MCP error vs HTTP vs DLR
| Symptom | Layer | Agent should |
|---|---|---|
| Tool throws / timeout | MCP wrapper | Retry once with same idempotency |
| HTTP 4xx | API validation/auth | Fix input; do not hammer |
| HTTP 2xx, no SMS | Phone / airtime / OEM | List devices, then a human |
| DLR failed | Operator | New OTP challenge if TTL allows |
Retries need Idempotency-Key
Same key for transport. New key only for a new business attempt. JSON example.
Not an IDE error toast product
Map structured errors in your wrapper. Not a first-party Cursor/Claude plugin.
Do not resend OTP blindly
OTP TTL lives in your app.
Overview vs this spoke
Keys if 401s.
Checklist
- Error codes distinguish layers.
- Idempotency on retry.
- OTP not duplicated.
- Phone last-seen checked.
- No plugin branding.
- Airtime called out on radio fail.
Next steps
Canary a forced fail, then devices + volume.
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
