Carrier errors
A subset of failures originate from the underlying mobile carrier and are bubbled up unchanged in the response message field. They generally return HTTP 200 with status: "FAIL" — the request itself was valid; the carrier refused.
The catalog below is the complete set of carrier message values you may receive. Descriptions are partner-neutral; raw per-carrier codes are not exposed and may change without notice.
message | Meaning |
|---|---|
INVALID_MSISDN | The MSISDN is not a valid mobile number for the given country. |
INVALID_MSISDN_LANDLINE | The MSISDN is a landline; mobile-only services cannot subscribe it. |
CARRIER_NOT_SUPPORTED | The detected carrier is not provisioned for requested service and country. |
FAILED_INIT_SUB | The carrier rejected the subscription initiation request. Retry once; if it persists, contact support. |
NOT_ALLOWED_CHANNEL | The carrier does not permit this channel (for example, USSD vs SMS) for this service. |
INVALID_PIN | The OTP submitted does not match. |
MAX_PIN_RETRIES | The user exceeded the maximum OTP attempts; restart the flow with a new init call. |
PIN_EXPIRED | The OTP has expired; restart the flow with a new init call. |
ALREADY_SUBSCRIBED | The MSISDN already has an active subscription to this service. |
INSUFFICIENT_FUNDS | The subscriber's balance is too low to be charged. |
SPENDING_LIMIT_REACHED | The subscriber hit their carrier-imposed spending limit. |
TRX_COUNT_REACHED | The subscriber hit their carrier-imposed transaction count limit. |
TRX_LIMIT_EXCEEDED | The subscriber exceeded the carrier's transaction limit. (Spelling reproduced verbatim — this is the exact message value sent on the wire.) |
INVALID_USER | The carrier reports the subscriber account is invalid or unknown. |
NOT_ELIGIBLE | The subscriber is not eligible for this service per carrier rules. |
BLACKLISTED | The subscriber is blacklisted by the carrier. |
BARRED | The subscriber's account is barred by the carrier. |
ERROR | Unspecified carrier error. Retry-safe. |
Use the values exactly as listed in the table.
Critical errors — stop retrying
The following codes are terminal for the given MSISDN. Retrying with the same number will not succeed and may consume a paid attempt with the carrier. Treat them as permanent rejections and surface them to your operations team:
INVALID_USERNOT_ELIGIBLEBLACKLISTEDBARRED
For all other carrier errors, a single bounded retry is reasonable; persistent failures warrant a support ticket to technical@noju.io.