Troubleshooting Messages and Calls

Use these checks to investigate rejected requests, missing messages or callbacks, and unexpected call behavior.

An API request fails authentication

• Confirm you are using the Account SID and Auth Token for the intended account.
• Base64-encode the literal AccountSid:AuthToken pair, including the colon, and send it as Authorization: Bearer <encoded credentials>.
• Use your API Auth Token for API requests and your Webhook Secret for webhook signature verification. They serve different purposes.

See Getting Started with TextGrid.

A message is rejected

Check the HTTP status and error response, then confirm:

• The sending number belongs to the intended account and is enabled for messaging.
• The recipient and sender are correctly formatted phone-number strings.
• The request includes message text or media.
• The recipient is not blocked by an opt-out or other applicable restriction.
• Any required campaign approval and number attachment have completed.

Error bodies vary and can be empty. Do not assume every failure includes the same error fields.

See Sending SMS and MMS and Managing Opt-ins and Opt-outs.

A campaign exists, but the number cannot send

Creating a campaign is only part of registration. The campaign needs the required approval, and the sending number must be attached to it.

An accepted attachment request does not mean attachment has completed. It usually completes within a few minutes, but can take up to a few days, especially over a weekend or legal holiday. Check the campaign and number association before sending or submitting another attachment request.

If the brand is unverified, submit a Brand Identity Appeal through the TextGrid Dashboard. This appeal is currently unavailable through the API.

See 10DLC Registration.

The send request succeeded, but the message was not delivered

A successful API response does not confirm delivery to the recipient.

Use the saved message SID to check the current message record and available delivery-status notifications. Review any reported error detail before sending again. For MMS, also check that the media URL can be retrieved and the content meets the supported media requirements.

Do not resend simply because a callback has not arrived. The original message may still have been accepted or delivered.

See Sending SMS and MMS and Messaging Webhooks.

An incoming message does not reach my webhook

• Retrieve the receiving number and check its smsUrl and smsMethod settings.
• Confirm the URL is reachable by TextGrid and the endpoint accepts the configured HTTP method.
• Read POST callbacks as form data and GET callbacks as query parameters, rather than expecting JSON.
• Check your server's request logs and response status.
• Respond promptly; the incoming-message timeout defaults to 15 seconds and can be configured.

The primary incoming-message retry occurs only for a transport result with status code zero. Returning HTTP 500 does not trigger another primary attempt. A configured fallback can be used under the conditions described in the webhook guide.

See Receiving SMS and MMS.

My application sends duplicate automatic replies

Check whether TextGrid already handles the message through subscription keywords or configured automatic responses. STOP, START, and HELP messages can still reach your incoming webhook after TextGrid processes them.

Avoid a generic application reply to subscription keywords. If TextGrid has already sent an automatic response, it skips your callback's reply TwiML, but that does not prevent a separate API send from your application.

Deduplicate incoming messages using their message identifiers, and do not send the same reply through both TwiML and the messaging API.

See Managing Opt-ins and Opt-outs.

An incoming call bypasses my instructions webhook

Check whether call forwarding is enabled for the number. Forwarding takes precedence: TextGrid forwards the call to the configured destination without requesting voiceUrl, even when that URL is set.

Disable forwarding if your webhook should control greetings, menus, and routing. Then check voiceUrl, voiceMethod, and your endpoint's request logs.

See Managing Phone Numbers and Receiving Voice Calls.

A call does not follow the expected instructions

• Return HTTP 200 with valid TwiML XML from instruction endpoints.
• Confirm you are returning instructions to the instruction request, rather than the final-status notification.
• Use implemented verbs and supported attributes; do not assume full Twilio compatibility.
• For keypad collection, use DTMF Gather with at most one child prompt, either Say or Play.
• Keep Digits as a string so leading zeros and keypad characters are preserved.
• Escape dynamic XML text correctly, including & and <.

When no TwiML instructions remain, the call hangs up automatically. An explicit Hangup is unnecessary after a final spoken message. If you do use it on a conferenced call, it ends the entire conference.

See Receiving Voice Calls and Voice Webhooks.

Answering-machine detection gives unexpected results

Detection depends heavily on the type of phone line and destination carrier. Accuracy and classification time vary; a human or answering machine can be classified incorrectly or later than expected.

Check the reported AnsweredBy and optional reason, and design the call flow to handle delayed or incorrect results. Test with the line types and carriers your recipients use.

See Making Voice Calls.

Webhook signature verification fails

Check these inputs before changing the signing algorithm:

• Use the receiving account's Webhook Secret exactly as displayed, without Base64-decoding it.
• Use the exact public URL requested by TextGrid, including scheme, hostname, path, and query string. A proxy's internal URL can differ.
• For GET, sign the complete requested URL with the query string included once.
• For POST, concatenate the callback URL, including its existing query string, directly with the unchanged raw body. Do not insert a separator.
• Preserve query encoding and order, POST whitespace, and the original body serialization.
• Apply the documented non-ASCII escaping to the signing text, then use UTF-8 byte arrays for HMAC-SHA1 and Base64-encode the hash.

For registration notifications, include the TCREvent query parameter in the signing URL. Verify your implementation against the synthetic vectors before testing real callbacks.

See Verifying Webhook Signatures.

A status callback is missing

Check which callback setting applies:

• Message delivery: The message's own statusCallback takes precedence; otherwise the sending number's configured status callback is used when available.
• Incoming call: The receiving number's statusCallback is used.
• Outgoing call: The call's StatusCallback is used.

Check the endpoint's configured method and server logs. Return an accepted acknowledgment: messaging status notifications accept HTTP 200, 201, 202, or 204; voice final-status notifications expect HTTP 200.

These status senders do not provide an automatic retry loop. Retrieve the message or call record to reconcile its current state. Some specialized call integrations handle events separately, so a generic callback is not guaranteed for every call leg.

See Messaging Webhooks and Voice Webhooks.

A request times out—should I retry?

A timeout can leave the outcome uncertain. The operation may have succeeded even though your application did not receive the response.

Check resource records and available callbacks before repeating a request that sends a message, places a call, purchases a number, or submits registration work. Repeating it can create duplicates or additional charges. An area-code purchase retry can acquire another number.

For preference updates, some recipients may already have been updated before an error occurred. Check recorded preferences before retrying the group.

Prepare information for support

Include the affected message, call, phone-number, brand, or campaign identifiers; the time and time zone; the HTTP status; and the relevant response or callback details. Explain what you expected and what happened instead.

Remove Auth Tokens, Webhook Secrets, Authorization headers, and unnecessary customer information before sharing logs.