Troubleshooting
Find the fix for common textbee problems: messages stuck in pending, failed sends, offline phones, missing incoming SMS, API errors and webhooks.
Updated
Most textbee problems have one of three causes: the API rejected the request, Android paused the app on the phone, or the carrier did not accept the message. Find your symptom in the table below and go to the page it names. Each page lists the checks in order, with a fix for each one.
Find your symptom
| Symptom | Likely cause | Go to |
|---|---|---|
A message stays in pending | The phone is asleep, a large batch is draining, or the message is scheduled | Messages not sending: stuck in pending |
A message has status: "failed" and an errorCode | The phone or the carrier rejected it | Messages not sending: failed with an errorCode |
| The API returns 400 | No enabled device, a disabled device, an unverified email, or the push to the phone failed | Messages not sending: did the API accept it |
| The API returns 401 | The API key is missing, invalid or revoked | Messages not sending: did the API accept it |
| The API returns 429 | A daily, monthly or per-batch plan limit is used up | Messages not sending: did the API accept it and Pricing |
The device shows offline, or lastHeartbeat is old | Android or the phone maker stops the app in the background | Keep the phone online |
A message is sent but never delivered, or shows delivery_failed | The carrier sends no delivery report, the report says not delivered, or the recipient's phone is off | Messages not sending: sent but not delivered |
| Incoming SMS do not appear | Receive SMS is off, the SMS permission is missing, or an SMS filter blocks them | Receiving SMS and SMS filters |
| Incoming SMS arrive late | The phone was offline or asleep and uploaded them later | Keep the phone online |
| A webhook does not arrive | The URL is private or not reachable, the endpoint returns 4xx (not retried) or keeps failing, or the subscription is paused. MESSAGE_RECEIVED is not sent for a message uploaded more than 48 hours after it arrived. | Webhooks |
Many messages fail with errorCode "5" | Android's own cap on outgoing SMS per app | Messages not sending: Android's outgoing cap |
Check the basics first
These three calls answer most questions. Run them before you change anything.
This call checks that your API key works:
curl https://api.textbee.dev/api/v1/gateway/stats \
-H "x-api-key: YOUR_API_KEY"This call lists your phones. Look at enabled and lastHeartbeat on each one:
curl https://api.textbee.dev/api/v1/gateway/devices \
-H "x-api-key: YOUR_API_KEY"This call shows every message from one send, with its status and errorCode:
curl "https://api.textbee.dev/api/v1/gateway/messages?smsBatchId=YOUR_BATCH_ID" \
-H "x-api-key: YOUR_API_KEY"On the phone, open the textbee app and go to Settings > Device health. The screen lists what can slow down or stop messages on this phone, and what to change.
Collect evidence before you ask for help
A support request with this information gets a faster answer:
| Item | Where to find it |
|---|---|
| Device id | The _id from GET /gateway/devices, the Device ID row in the app settings, or the Devices panel in the dashboard |
smsId or smsBatchId | The send response, or the message from GET /gateway/messages |
| Timestamps | requestedAt, dispatchedAt, sentAt, failedAt on the message, and the time you sent the request, with a timezone |
status, errorCode and errorMessage | The message from GET /gateway/messages |
| API status code and response body | Your application log |
| App version | The App Version row in the app settings, or appVersionName on the device |
| Phone model and Android version | brand, model and osVersion on the device |
| Device health | A screenshot of Settings > Device health in the app |
Do not send your API key. Nobody at textbee needs it.
Where to get help
- Discord: ask the community at textbee.dev/discord.
- Email: write to support@textbee.dev with the evidence above.
- Status page: check status.textbee.dev for an outage before you debug your own setup.
- Self-hosted instance: open an issue on GitHub. See Self-hosting textbee.