Troubleshooting SMS

Start with the symptom below. Do not capture or send packet traces containing message content or credentials unless support specifically requests a safe capture.

An outbound API request fails

Check the HTTP status and JSON error response:

400: check E.164 formatting and whether the content exceeds six SMS parts.
401: request a new token and check the Authorization: Bearer header.
404: check that from is assigned to the organisation that issued the token. The same 404 is also returned when the destination has no outbound SMS rate on your account, so if the from number checks out, contact support with the destination country and the X-Request-Id.
503: wait briefly, but do not retry automatically if the result is unknown.

Record the X-Request-Id response header when it is present.

The send-SMS request has no idempotency key. Retrying after a timeout or unknown response can send and charge another message.

The API succeeds but the message is not delivered

A successful API response means the message was accepted for sending. Check the delivery receipt for the final status.

If no receipt arrives, check that the original request included a reachable dlrUrl.

My inbound SMS webhook receives nothing

Check that:

An SMS endpoint is assigned to the receiving number.
The endpoint URI starts with https://.
DNS resolves publicly.
The TLS certificate is valid and has not expired.
Your handler accepts JSON POST requests and returns 2xx.

cloudnumbering retries a delivery only when it cannot reach your server, such as a connection failure or timeout. Once your server responds, the message is not sent again: an error response is not retried, and a redirect counts as delivered without being followed. Serve the handler directly at the configured URL.

My inbound SMS email does not arrive

Check the mailto: address, spam filtering, quarantine, and mailbox rules. Confirm that the email endpoint is assigned to the intended number.

A multipart message costs more than expected

Each SMS part is charged separately when the message is submitted, and the charge is not refunded if the network rejects the message afterwards — so a message with a rejected delivery receipt still carries its charge. Unicode content fits fewer characters per part, and some GSM-7 extension characters count twice. See Understanding SMS encoding and message length.

Contact support

If the checks above do not resolve the issue, send support three recent examples where possible. Include:

UTC timestamp.
Direction: inbound or outbound.
Masked to and from numbers.
Message sid for outbound SMS.
Delivery status or safe error text.
X-Request-Id, if present.

Do not include access tokens, client secrets, or message content unless support explicitly asks for it through an approved secure channel.