Skip to content

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.

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.

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.

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.

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.

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.

  • 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).
  • 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 shows lastStatusCode and lastError.
  • The endpoint redirects. Redirects count as failures: use the final URL.
  • A firewall blocks SMSFabric. Allow incoming POST from the internet on that path, and rely on the signature for trust.
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.

Include the requestId from the error response, the message or object id, and the time. Never send your API key or webhook secret.