Errors
Every error has the same shape: an error object with a stable code you can program against and a message in English for people.
{ "error": { "code": "invalid_phone", "message": "The phone number is not valid. Use E.164, e.g. +905321234567." } }
invalid_code adds one field, attemptsLeft:
Response · 422
{
"error": {
"code": "invalid_code",
"message": "The code is not correct.",
"attemptsLeft": 4
}
}Error codes#
| Code | HTTP | Meaning | What to do |
|---|---|---|---|
invalid_api_key | 401 | The key is missing, unknown or revoked. | Send Authorization: Bearer <key> with an active key. |
rate_limited | 429 | More than 60 requests in a minute with this key. | Wait the number of seconds in Retry-After, then retry. |
validation_error | 422 | A field has the wrong type or is out of range (e.g. ttlSec, limit, requestId). The message names the field. | Fix the request. Not worth retrying. |
validation_error | 400 | The body is not valid JSON. | Send a JSON body with Content-Type: application/json. |
invalid_phone | 422 | to is missing or not a valid number. | Send E.164 (+905321234567); see Phone numbers. |
missing_text | 422 | text is missing or blank. | Send a non-empty text. |
text_too_long | 422 | The text needs more than 6 SMS parts, or is over 2,000 characters. | Shorten it; see Limits. |
limit_reached | 402 | The workspace has used all messages of its plan this month. | Upgrade the plan or wait for the 1st of next month (UTC). |
plan_feature_unavailable | 403 | The workspace's plan doesn't include this endpoint (OTP). | Upgrade the plan. |
email_not_verified | 403 | The workspace owner hasn't confirmed their email address yet (POST /messages, POST /otp/send). | The owner clicks the link in the "Confirm your email" message (or resends it from the dashboard banner). |
demo_workspace | 403 | The workspace is a demo (the account shown to app store reviewers): nothing is ever sent (POST /messages, POST /otp/send). | Use your own workspace. |
not_found | 404 | No message with this id in your workspace. | Check the id; ids of other workspaces are never visible. |
device_not_found | 422 | deviceId is not an active phone of this workspace. | Use an id from GET /v1/devices, or leave deviceId out. |
otp_rate_limited | 429 | Too many codes sent to this number. | Wait the seconds in Retry-After. |
otp_not_found | 422 | No open code for this number and purpose (never sent, already used, or replaced by a newer one). | Send a new code. |
otp_expired | 422 | The code's time is up. | Send a new code. |
invalid_code | 422 | Wrong code; attemptsLeft says how many tries remain. | Let the user try again. |
too_many_attempts | 429 | 5 tries were used; the code is locked, even if the next one is right. | Send a new code. |
Unexpected server errors return HTTP 5xx. They are rare and safe to retry with back-off; send a requestId with messages so a retry never sends twice.
Examples#
curl -X POST "https://sms.liscosolutions.com/v1/messages" \
-H "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"to":"12","text":"Hello"}'const res = await fetch("https://sms.liscosolutions.com/v1/messages", {
method: "POST",
headers: {
Authorization: "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
to: "12",
text: "Hello"
}),
});
console.log(res.status, await res.json());<?php
$ch = curl_init("https://sms.liscosolutions.com/v1/messages");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"to" => "12",
"text" => "Hello",
]),
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
print_r([$status, $body]);import requests
res = requests.post(
"https://sms.liscosolutions.com/v1/messages",
headers={"Authorization": "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
json={
"to": "12",
"text": "Hello",
},
)
print(res.status_code, res.json())Response · 422
{
"error": {
"code": "invalid_phone",
"message": "The phone number is not valid. Use E.164, e.g. +905321234567."
}
}curl -X POST "https://sms.liscosolutions.com/v1/messages" \
-H "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"to":"+905321234567"}'const res = await fetch("https://sms.liscosolutions.com/v1/messages", {
method: "POST",
headers: {
Authorization: "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
to: "+905321234567"
}),
});
console.log(res.status, await res.json());<?php
$ch = curl_init("https://sms.liscosolutions.com/v1/messages");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"to" => "+905321234567",
]),
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
print_r([$status, $body]);import requests
res = requests.post(
"https://sms.liscosolutions.com/v1/messages",
headers={"Authorization": "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
json={
"to": "+905321234567",
},
)
print(res.status_code, res.json())Response · 422
{
"error": {
"code": "missing_text",
"message": "The message text is required."
}
}curl -X POST "https://sms.liscosolutions.com/v1/messages" \
-H "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"to":"+905321234567","text":"Hello","ttlSec":10}'const res = await fetch("https://sms.liscosolutions.com/v1/messages", {
method: "POST",
headers: {
Authorization: "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
to: "+905321234567",
text: "Hello",
ttlSec: 10
}),
});
console.log(res.status, await res.json());<?php
$ch = curl_init("https://sms.liscosolutions.com/v1/messages");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"to" => "+905321234567",
"text" => "Hello",
"ttlSec" => 10,
]),
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
print_r([$status, $body]);import requests
res = requests.post(
"https://sms.liscosolutions.com/v1/messages",
headers={"Authorization": "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
json={
"to": "+905321234567",
"text": "Hello",
"ttlSec": 10,
},
)
print(res.status_code, res.json())Response · 422
{
"error": {
"code": "validation_error",
"message": "ttlSec must be a whole number from 60 to 86400."
}
}curl "https://sms.liscosolutions.com/v1/messages/000000000000000000000000" \
-H "Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"const res = await fetch("https://sms.liscosolutions.com/v1/messages/000000000000000000000000", {
headers: {
Authorization: "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
},
});
console.log(res.status, await res.json());<?php
$ch = curl_init("https://sms.liscosolutions.com/v1/messages/000000000000000000000000");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
],
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
print_r([$status, $body]);import requests
res = requests.get(
"https://sms.liscosolutions.com/v1/messages/000000000000000000000000",
headers={"Authorization": "Bearer lsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
)
print(res.status_code, res.json())Response · 404
{
"error": {
"code": "not_found",
"message": "No such resource in this workspace."
}
}