الأخطاء
لكل خطأ الشكل نفسه: كائن error فيه رمز ثابت code تبني عليه منطق برنامجك، ورسالة message بالإنكليزية للبشر.
{ "error": { "code": "invalid_phone", "message": "The phone number is not valid. Use E.164, e.g. +905321234567." } }
يضيف invalid_code حقلًا واحدًا هو attemptsLeft:
الرد · 422
{
"error": {
"code": "invalid_code",
"message": "The code is not correct.",
"attemptsLeft": 4
}
}رموز الأخطاء#
| الرمز | HTTP | المعنى | ما العمل |
|---|---|---|---|
invalid_api_key | 401 | المفتاح مفقود أو غير معروف أو ملغى. | أرسل Authorization: Bearer <key> بمفتاح نشط. |
rate_limited | 429 | أكثر من 60 طلبًا في دقيقة بهذا المفتاح. | انتظر عدد الثواني في Retry-After ثم أعد المحاولة. |
validation_error | 422 | حقل بنوع خاطئ أو خارج النطاق (مثل ttlSec أو limit أو requestId). تذكر الرسالة اسم الحقل. | صحّح الطلب. لا فائدة من إعادة المحاولة. |
validation_error | 400 | جسم الطلب ليس JSON صالحًا. | أرسل JSON مع Content-Type: application/json. |
invalid_phone | 422 | to مفقود أو ليس رقمًا صالحًا. | أرسل الرقم بصيغة E.164 (+905321234567)؛ راجع أرقام الهواتف. |
missing_text | 422 | text مفقود أو فارغ. | أرسل نصًا غير فارغ. |
text_too_long | 422 | يحتاج النص إلى أكثر من 6 أجزاء SMS، أو يتجاوز 2000 حرف. | اختصره؛ راجع الحدود. |
limit_reached | 402 | استهلكت مساحة العمل كل رسائل خطتها هذا الشهر. | رقِّ الخطة أو انتظر أول الشهر القادم (UTC). |
plan_feature_unavailable | 403 | خطة مساحة العمل لا تشمل نقطة النهاية هذه (رموز التحقق). | رقِّ الخطة. |
email_not_verified | 403 | لم يؤكّد مالك مساحة العمل بريده الإلكتروني بعد (POST /messages وPOST /otp/send). | يضغط المالك على الرابط في رسالة «أكّد بريدك الإلكتروني» (أو يعيد إرسالها من الشريط في لوحة التحكم). |
demo_workspace | 403 | مساحة العمل تجريبية (الحساب المعروض على مراجعي متاجر التطبيقات): لا يُرسل منها أي شيء (POST /messages وPOST /otp/send). | استخدم مساحة العمل الخاصة بك. |
not_found | 404 | لا رسالة بهذا المعرّف في مساحة عملك. | تحقّق من المعرّف؛ معرّفات مساحات العمل الأخرى لا تظهر أبدًا. |
device_not_found | 422 | deviceId ليس هاتفًا نشطًا في مساحة العمل هذه. | استخدم معرّفًا من GET /v1/devices أو احذف deviceId. |
otp_rate_limited | 429 | أُرسل عدد كبير من الرموز إلى هذا الرقم. | انتظر الثواني في Retry-After. |
otp_not_found | 422 | لا رمز مفتوح لهذا الرقم والغرض (لم يُرسل، أو استُخدم، أو حلّ محله رمز أحدث). | أرسل رمزًا جديدًا. |
otp_expired | 422 | انتهت مدة صلاحية الرمز. | أرسل رمزًا جديدًا. |
invalid_code | 422 | رمز خاطئ؛ يبيّن attemptsLeft عدد المحاولات المتبقية. | دع المستخدم يحاول مجددًا. |
too_many_attempts | 429 | استُنفدت المحاولات الخمس؛ قُفل الرمز حتى لو كانت المحاولة التالية صحيحة. | أرسل رمزًا جديدًا. |
تعيد أخطاء الخادم غير المتوقعة رمز HTTP من فئة 5xx. وهي نادرة، وإعادة المحاولة معها آمنة مع مهلة متزايدة؛ أرسل requestId مع الرسائل حتى لا تتسبب إعادة المحاولة في إرسال مزدوج.
أمثلة#
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())الرد · 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())الرد · 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())الرد · 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())الرد · 404
{
"error": {
"code": "not_found",
"message": "No such resource in this workspace."
}
}