Refusal reasons

Every text the SMS calls can answer when they refuse a request, what it means and what to do. The texts are
written for developers; show your own wording to your users.

How a refusal arrives

A request is checked in this order. The first check that fails answers.

Step	Answer	Where the text is
1. Are the required fields there?	HTTP 400	`errorMessages`
2. Is the API key good, and is the caller's address allowed?	HTTP 401	`message`
3. Are too many sends in progress? (send calls only)	HTTP 429 with `Retry-After`	`ErrorMessages`
4. Can this message be sent?	HTTP 200 with `status: "F"`	`remarks`

So for the send calls, always read status, not only the HTTP code. See Errors
for the shape of each body.

For every refusal on this page nothing was sent, with one exception that is marked below.

Before the call runs (all calls)

HTTP	Text	Cause	What to do
400	`The ApiId field is required.`	The API key is missing.	Send the key: `api_id` in the JSON body of a POST or in the query of a GET. The SMS records calls name it `apiId`. On a POST, a key in the address is not read.
400	`The SenderId field is required.`	`sender_id` is missing.	Send it.
400	`The PhoneNumber field is required.`	`phonenumber` is missing.	Send it.
401	`Access denied: your IP is not in the allowed list. Configure your allowed IPs in the partner portal.`	One text, three possible causes: the key is not known (also after the key was replaced); the account is not active; or the account has a list of allowed IP addresses and your address is not on it.	Check the key first, then the state of the account, then the list of allowed addresses.
429	`Too many concurrent requests. Retry in 5s.`	Too many of your send calls are in progress.	Wait the seconds in the `Retry-After` header and send the same request again. See Limits.

Send SMS and Send SMS to many numbers

HTTP 200, status: "F", message_id: 0, the text in remarks.

Text in `remarks`	Cause	What to do
`One of SmsType or RatePlanId is required`	Neither `sms_type` nor `rate_plan_id` was sent.	Send `sms_type` (`T`, `P` or another value) or `rate_plan_id`.
`One of TextMessage or TemplateId is required`	Neither `textmessage` nor `templateid` was sent.	Send the text.
`To send single text to multiple numbers use SendSMSMulti endpoint`	`phonenumber` holds a comma in the one-number call.	Use Send SMS to many numbers.
`Invalid phone number format: use the international E.164 format, e.g. 37491234567`	The number is not 8 to 15 digits with an optional `+`, or it starts with `0`, or it has spaces, dashes or brackets.	Send the number with its country code, digits only. See Addresses and formats.
`Invalid phone number format: 1 of 3 phone numbers (position 2) is not in the international E.164 format, e.g. 37491234567; the whole request was refused`	In a call with several numbers, at least one is wrong. An empty entry, for example after a comma at the end, counts as wrong. The text names up to ten positions, counted from 1.	Fix or remove the numbers at those positions and send the whole list again. Nothing was sent to the good numbers either.
`SenderId is not found`	Your account has no SMS sender name written exactly like this. Capital and small letters count.	Take the name from List sender names and write it the same way.
`Sender is not found`	The sender name is yours but cannot be used now: it is waiting for approval, was declined or was switched off.	Check it with Get sender name status and use it when the status is `Approved`.
`Rate Plan is not found`	No price plan fits: the `rate_plan_id` is not one of yours, or your account has no plan for this `sms_type`.	Take `rate_plan_id` from List rate plans, or contact support to get a plan for this kind of message.
`Template is not found`	`templateid` is unknown, is not an SMS template, or is not approved.	Use the id of one of your approved SMS templates.
`Not valid sms contacts provided`	Your price plan has no price for the country or operator of the number.	Check the number. To send to this destination, ask support to add it to your plan.
`Insufficient balance`	The price of this request is more than the balance you can use. Messages that are scheduled or still being sent are counted against the balance.	Top up, or wait for waiting messages to finish, then send again.
`Failed to send the message`	The request passed the checks but the send step stopped.	Do not assume it was sent or not sent. Look the message up with List SMS records by your `uid` before you send again.
`User is not found`, `Open sender is not allowed for this user`, `Incorrect sender id routing`, `Invalid rate plan`, `Invalid rate`, `Not valid contacts provided`	Something in the set-up of your account, sender name or price plan does not fit.	Contact support with the text and the time of the call.
Any other text	An unexpected error.	Contact support with the exact text and the time of the call. Check the records before you send again.

Send a verification code

HTTP 200, status: "F", verification_id: 0, the text in remarks. The texts and their meaning are the same
as for Send SMS above: Invalid phone number format: …, SenderId is not found, Sender is not found,
Rate Plan is not found (your account has no price plan for one-time codes), Not valid sms contacts provided,
Insufficient balance and Failed to send the message.

If remarks is empty, the code could not be saved: ask for a new code.

Check a verification code

Answer	Text in `remarks`	Cause	What to do
HTTP 200, `status: "F"`	`Verification Code is Not Verified`	One text for every failure: the code is wrong, the id is not known or is not yours, or a field did not arrive.	Check the two field names first: they are `verfication_id` and `verfication_code`, without an `i` after `ver`. A field sent under another name is read as 0. Then check the id and the code.

Balance, sender names and SMS records

Call	HTTP	Text	Cause	What to do
Get sender name status	400	`SenderId is not found`	`request_id` is missing, unknown or not yours.	Send the id of one of your own sender name requests.
Get an SMS record	400	`Report is not found`	No record with this id, or it is not yours.	Use an id from List SMS records.
List rate plans, List SMS records	400	`The field PageSize must be between 1 and 1000.`	`pageSize` is out of range.	Use 1 to 1000.
List SMS records	400	`Comparer value can be Equals,Contains,GreaterOrEquals,LessOrEquals or 1,2,3,4`	A filter has an unknown `comparer`.	Use one of the listed values.
List SMS records	400	`Direction value can be Asc,Desc or 1,2`	A sorting has an unknown `direction`.	Use `Asc` or `Desc`.
Any	422	`Unknown error occurred`	Something failed on our side, or a value has the wrong type.	Check the request. If it is right, contact support with the time of the call.

What "accepted" means

Call	`status`	`remarks`
Send SMS, Send SMS to many numbers	`S`	`Message submitted successfully`
Send a verification code	`S`	`Verification code sent successfully`
Check a verification code	`V`	`Verification Code is Verified`

S means we accepted the message for sending. It does not mean the phone received it, or that the mobile
network took it. Learn the result from the delivery report.

Things that are not refused

These pass without an error, so check them on your side.

Long text. There is no length limit. A long text is sent as several parts and each part is charged: 160
characters fit in one part and 153 in each part of a longer text. With characters outside the basic SMS
alphabet (for example Armenian or Cyrillic letters) the figures are 70 and 67.

Numbers without a price in a many-numbers call. A number whose country or operator is not in your price
plan is left out without an error, and the answer is still S when at least one number remains. Such a
number has cost: null in client_costs. Read client_costs to see who will not get the message.

Any sms_type. T is the plan for one-time codes and P the plan for promotional messages. Any other
value is accepted and treated as transactional.

Placeholders in the text. {{name}}, {{surname}}, {{email}} and {{url}} in textmessage are
removed, because a call with an API key carries no contact data. Write the final text yourself.

callback_url. The address is not checked when you send. A wrong address means no delivery report.

Refusal reasons

How a refusal arrives#

Before the call runs (all calls)#

Send SMS and Send SMS to many numbers#

Send a verification code#

Check a verification code#

Balance, sender names and SMS records#

What "accepted" means#

Things that are not refused#