Messages are accepted but not arriving
Every call returns success. Work through this in order — the first four checks do not involve the carrier at all.
Read this article →Messages that fail with an error code
A failed status always carries a reason. The first question is which layer wrote it — the platform or the provider.
Two kinds of code
A failure is either the platform refusing the request before it left, or the provider refusing it after. The code tells you which, and therefore who owns the fix.
| Code | Layer | Typical cause |
|---|---|---|
| 40000 | Platform (HTTP 400) | Bad parameter, key bound to no channel, no ACTIVE channel, messageType not recognised |
| 40100 | Platform (HTTP 401) | Key missing or invalid |
| 40400 | Platform (HTTP 404) | messageId not found, or belongs to another tenant |
| 42900 | Platform (HTTP 429) | Submission rate exceeded — back off and retry |
| errorCode + rawStatus | Provider | The provider's own refusal, kept verbatim so you can match it against their documentation |
Work the provider refusal
Read rawStatus before errorCode
It is the provider's own wording, so it matches their docs and support answers directly.
Check encoding and segments
A message that unexpectedly jumped encoding can be refused for length. A wide-encoding segment budget is much smaller than a GSM one.
Check the sender number
A number the provider has not approved for that route is refused per message, even on an ACTIVE connection.
Compare channels
If only one provider is refusing, the log's channel comparison tells you immediately — and routing can move traffic off it while you investigate.
Note. A provider refusal is not billed, which is a useful signal: a message with a null providerMessageId never became an accepted send on the provider side.
Platform refusals are the easy ones
A 40000 on every call usually means a binding problem rather than a payload problem — most often a key that was never bound to a channel, or a connection that is no longer ACTIVE. Both are console fixes, not code changes.
Keep reading
A recipient received the same message twice
Almost always this is a client-side timeout followed by a resend. Here is how to confirm it, and how to stop it happening.
Read this article →A provider stopped accepting traffic
Telling an account-level failure apart from a bad route, and what failover can and cannot absorb for you.
Read this article →