Handling Failures
"Failed" covers two different situations that call for different responses: the phone tried and the network rejected it, or the phone never got a chance to try at all.
What the API tells you
GET /api/v1/sms/<message_id>/ will show "status": "failed", but the v1 API's response does not currently include a failure reason field — that level of detail isn't exposed outside the dashboard yet. If you need to know why a specific message failed, check that message on the dashboard rather than relying on the API response alone.
What typically causes it
- The SIM tried and the carrier rejected it — a malformed or unreachable destination number, a carrier-side block, or no signal at the moment of sending. This reports back quickly, usually well within the first poll cycle.
- The SIM never reported back at all — it claimed the message, then went offline (dead battery, killed app, pulled SIM) before confirming anything. Connecfy retries this automatically up to 3 times over several minutes before giving up — see Message Lifecycle. If it's still failing after retries, that SIM was offline for the entire retry window, not just briefly.
What to do about it
- Validate destination numbers before sending where you can — a 400 at send time is cheaper to handle than a failure discovered minutes later.
- If failures cluster around one SIM, check its status — see SIM Offline.
- Don't auto-retry a
failedmessage by calling send again with the same content unless you mean to send it twice —failedis already the end of Connecfy's own retry attempts, not a transient state you're expected to nudge forward.
What isn't a failure
A message sitting at sent with no further update is very often fine — not every carrier returns a delivery receipt, so the absence of delivered doesn't mean anything went wrong. Only failed is an actual failure signal.