Troubleshooting
Start with the message: open it in the portal’s Messages screen, or call GET /v1/messages/:id and read status, errorCode and the events timeline. Most problems show up there.
Messages stay queued
Section titled “Messages stay queued”| Cause | How to tell | Fix |
|---|---|---|
| No phone online | GET /v1/devices shows every phone offline; the timeline has wake_sent. |
Open the SMSFabric app on the phone, check its connection, and exclude it from battery optimization (Battery). |
| Scheduled or outside the send window | scheduledAt is in the future, or your preferences have a sendWindow. |
Wait, or change the send window in Settings → Sending. |
| Phone or SIM disabled | The device’s enabled is false, or the SIM’s. |
Enable it in Devices. |
| SIM daily limit reached | The SIM’s dailyLimit is set. |
Raise the limit, or send through a pool with more SIMs. |
Messages stay routed
Section titled “Messages stay routed”The phone was told to send but hasn’t confirmed. Usually it is asleep or lost its connection. Check lastSeenAt on the device. In a pool, the message moves to another phone after 10 seconds; outside a pool it waits for that phone.
Messages failed
Section titled “Messages failed”Read errorCode:
errorCode |
Fix |
|---|---|
no_device_available |
Pair a phone, or enable one. |
radio_off |
The phone is in airplane mode or the radio is off. |
no_service |
No signal. Move the phone or check the SIM. |
generic_failure |
Often no balance, or the carrier blocked the message. Send a test from the phone’s own SMS app. |
limit_exceeded |
Android’s own sending limit was hit. Increase the cooldown in preferences, or spread traffic over more phones. |
short_code_not_allowed, short_code_never_allowed |
Android blocks sending to that short code. |
sim_not_found |
The SIM was removed. Re-insert it, or choose another SIM. |
device_rejected, device_unavailable |
The phone refused the message or was disabled. Check the app on the phone. |
tenant_suspended |
Contact support. |
Messages sent but never delivered
Section titled “Messages sent but never delivered”The carrier accepted the message but no delivery report came back. Some networks and some handsets don’t send reports. If the recipient says they didn’t get it, check that the number is right and that it isn’t a landline.
Messages blocked
Section titled “Messages blocked”errorCode is blacklisted, opted_out or campaign_canceled. Check the blacklist: a recipient who replied STOP is there with source opt_out, and is removed only when they reply START.
Webhook signatures don’t verify
Section titled “Webhook signatures don’t verify”- You verified the parsed and re-serialized JSON instead of the raw body. Use the exact bytes received (how).
- You used the wrong secret. Each endpoint has its own
whsec_secret. - Your server’s clock is off by more than 5 minutes. Sync it with NTP.
- A proxy in front of your app changed the body (for example by re-encoding it).
Webhooks aren’t arriving
Section titled “Webhooks aren’t arriving”- The endpoint isn’t subscribed to that event, or is disabled. Check Developers → Webhooks.
- Your endpoint answers something other than
2xx, or takes more than 10 seconds. The delivery list showslastStatusCodeandlastError. - The endpoint redirects. Redirects count as failures: use the final URL.
- A firewall blocks SMSFabric. Allow incoming
POSTfrom the internet on that path, and rely on the signature for trust.
API errors
Section titled “API errors”| Error | Fix |
|---|---|
401 invalid_api_key |
Check the key for whitespace or a cut-off value; it was maybe revoked. |
403 missing_permission |
The key lacks a scope. Create one with it (scopes). |
403 api_key_not_allowed |
Do this in the portal: the endpoint is for signed-in users only. |
404 not_found for an id you know |
The key belongs to another organization. |
400 validation_failed |
Read errors[]: each entry names the field. |
429 rate_limited |
Wait Retry-After seconds (Rate limits). |
The full list is in Errors. For phone app problems, see Mobile troubleshooting.
Contact support
Section titled “Contact support”Include the requestId from the error response, the message or object id, and the time. Never send your API key or webhook secret.