A carrier error code is the reason attached by the operator to a failed SMS, such as unknown subscriber, absent subscriber, barred or blocked by filter, mapped by gateways to plain-language failure reasons.
When a carrier cannot deliver a message, the failure comes back with a code from the systems that tried: errors from the mobile network's signalling, with names such as unknown subscriber, absent subscriber or call barred, status values inside an SMPP receipt, or an operator's own numbering. The codes differ by operator, by protocol and sometimes by software version, and the same switched-off phone can produce different codes on two networks. Gateways therefore translate them into a dozen or so stable reasons, such as unknown number, absent subscriber, barred, filtered, unsupported and network error, and keep the raw code for the cases where a support team needs it.
The reason decides the action, which is why the mapping matters more than the number:
- Remove unknown numbers at once, and barred ones that keep failing.
- Retry later for absent subscribers and temporary network errors.
- Change something for filtered messages: the sender, the wording or the link.
- Escalate network errors that cluster on one operator.
Hypothetically, a campaign shows 150 failures with the reason network error, 140 of them on one operator and all with the same raw code. The reason alone says retry later; the cluster says escalate, and the raw code is what lets the route be checked. The guide to why SMS fail walks through each reason in turn.
Two mistakes are common in code:
- Branching on raw codes in application logic. They vary by operator; branch on the plain reason and store the raw code beside it.
- Treating every failure as permanent, and deleting numbers that were only absent.
At SMSMeteor: every failed message carries the raw carrier code and its plain-English reason: as carrier_code and failure_reason in the API's message object, as carrier_code and reason in the message.failed webhook, and in the report, where failures are grouped into about twelve plain reasons. CSV and JSON exports include the carrier code with each message.
