SMS API errors and message statuses: what each one means and what to do

The short answer: the HTTP code tells you the kind of problem. On a 422, details.reason says what failed and details.field which field. An accepted message (201) can still fail later: its status becomes failed, with error: delivery_failed, and the credits go back to your balance.

HTTP codes

Code	What it means	What to do
201	The message was accepted	Keep the id and follow the status
401	The key is missing or not valid	Check the Authorization: Bearer ... header, that the key is complete and that it is still within the expiry you gave it
403 insufficient_scope	The key lacks the permission	Use a key with sms:write to send, or sms:read to look things up
404	What you asked for does not exist	Check the address and the id
409	The same Idempotency-Key arrived with a different body	Use a new key for each new request
422 validation_failed	The request failed validation	Read details.reason and details.field (next table)
429	Too many requests: the limit is 300 per minute per account	Wait a moment and retry; watch X-RateLimit-Remaining
503 disabled	The service is unavailable	Try again later

SMS reasons on a 422

details.reason	What happened	What to do
invalid_number	The number is not valid	Check the digits: there should be 9, starting with 8 (Mozambique) or 9 (Angola), such as 841234567; or write the number with the country code
text_required	The text is empty	Send a filled-in text field
text_too_long	The text is over 1,600 characters	Shorten the message
word_not_allowed	The message contains a word that is not allowed	Rewrite it without that word
sender_not_approved	The sender is not approved on your account	Use an approved sender (see GET /v1/sms/senders) or drop sender to send from NETMSG
number_opted_out	The number is on your account’s do-not-send list	Do not send to it; the list is at GET /v1/sms/opt-outs
country_not_available	The number is in a country we do not send to	Send only to mobiles in Mozambique and Angola
daily_limit_reached	The account’s daily sending limit was reached	Check daily_limit and sent_today in GET /v1/sms/balance and spread your sends
insufficient_credits	There are not enough credits	Buy credits on the SMS page in My MozOut

You may also get sms_reseller_required: the SMS account is not active. Activate the service on the SMS page in My MozOut and send the request again.

Message statuses

Status	In the history	What it means
queued	In queue	Waiting to go out
sending	Sending	Going out now
sent	Sent	Handed over to the mobile network
failed	Failed	Did not go out; the credits were returned
cancelled	Cancelled	The send was cancelled
simulated	Simulated	Sandbox only: validated, not sent or charged

sent does not mean “read” or “confirmed on the phone”. It means the message was handed over to the mobile network. And a message in failed has already been tried twice more, 10 minutes apart: check the number before you send it again.

Retrying without sending twice

If a request gets no answer (a network error, a timeout), you cannot tell whether the SMS was accepted. Repeat it with the same Idempotency-Key and the same body: if the first one got through, you receive the same response and no second SMS goes out. On a 429, wait before retrying. On a 422, retrying will not help: first fix what details.reason points to.

Need help with a specific request? Open a support ticket in My MozOut and quote the response’s X-Correlation-ID: that is how we find it quickly. To start from the beginning, see sending SMS through the API.

Want to review the SMS API operations and limits? It is all on the API page.

See the API page

Categories

Categories