عندما يفشل طلب، ترد الواجهة البرمجية بحالة HTTP ومحتوى من نوع application/problem+json (RFC 9457 ). اعتمد في منطقك على code لا على detail: الرموز ثابتة، أما النص المقروء فقد يتغير.
" type " : " https://docs.smsfabric.com/errors/validation_failed " ,
" detail " : " The request is invalid " ,
" code " : " validation_failed " ,
{ " field " : " to[1] " , " message " : " must be a valid E.164 phone number " },
{ " field " : " metadata " , " message " : " must be at most 4096 bytes of JSON " }
" requestId " : " req_u7x0a3d6g9j2m5p8s1v4y7b0 "
الحقل
المعنى
type
رابط URI يسمي المشكلة.
title
نص حالة HTTP.
status
حالة HTTP مكررة.
detail
ما الخطأ، موجها إلى إنسان. قد تتغير صياغته.
code
رمز ثابت للآلات، مذكور أدناه.
errors
يظهر في أخطاء التحقق: مدخل لكل حقل غير صالح. الحقول المتداخلة تُكتب بالنقاط (quietHours.start)، وعناصر المصفوفات بالأقواس (to[1]).
params
يظهر عند رفض بسبب الباقة: القيم التي يقوم عليها detail (الباقة والحد وما بلغ حده ووقت التجدد)، لتصوغ رسالة الخطأ بنفسك. انظر أخطاء الباقة .
requestId
اذكره عند التواصل مع الدعم.
الحقول غير المعروفة في محتوى الطلب تُرفض أيضا (validation_failed مع رسالة مثل property foo should not exist)، فلا يمر خطأ إملائي في اسم حقل بصمت.
curl -s https://api.smsfabric.com/v1/messages \
-H " X-Api-Key: $SMSFABRIC_API_KEY " \
-H " Content-Type: application/json " \
-d ' {"to": "+2010", "body": "Hello"} '
# {"type":"https://docs.smsfabric.com/errors/validation_failed","title":"Bad Request","status":400,
# "detail":"The request is invalid","code":"validation_failed",
# "errors":[{"field":"to[0]","message":"must be a valid E.164 phone number"}],"requestId":"req_…"}
import { SMSFabric , SMSFabricError } from ' @smsfabric/sdk ' ;
const sf = new SMSFabric ({ apiKey : process . env . SMSFABRIC_API_KEY });
await sf . messages . send ({ to : ' +2010 ' , body : ' Hello ' });
if (!( err instanceof SMSFabricError )) throw err ;
// status 0 means the request never got an answer (network error or timeout).
console . error ( err . status , err . code , err . detail , err . requestId );
for ( const field of err . errors ?? []) console . error ( `${ field . field } : ${ field . message }` );
" https://api.smsfabric.com/v1/messages " ,
headers ={ " X-Api-Key " : os . environ [ " SMSFABRIC_API_KEY " ]},
json ={ " to " : " +2010 " , " body " : " Hello " },
print ( res . status_code , problem [ " code " ], problem . get ( " detail " ), problem . get ( " requestId " ))
for field in problem . get ( " errors " , []):
print ( f ' { field [ " field " ] } : { field [ " message " ] } ' )
$ ch = curl_init ( ' https://api.smsfabric.com/v1/messages ' );
CURLOPT_POSTFIELDS => json_encode ([ ' to ' => ' +2010 ' , ' body ' => ' Hello ' ]),
CURLOPT_HTTPHEADER => [ ' X-Api-Key: ' . getenv ( ' SMSFABRIC_API_KEY ' ), ' Content-Type: application/json ' ],
CURLOPT_RETURNTRANSFER => true ,
$ body = json_decode ( curl_exec ($ ch ), true );
$ status = curl_getinfo ($ ch , CURLINFO_RESPONSE_CODE );
echo "$ status {$ body [' code ']} {$ body [' detail ']} {$ body [' requestId ']} \n " ;
foreach ($ body [ ' errors ' ] ?? [] as $ field ) {
echo "{$ field [' field ']} : {$ field [' message ']} \n " ;
الحالة
إعادة المحاولة؟
400 و401 و403 و404 و413 و415 و422
لا. أصلح الطلب أو المفتاح أو البيانات أولا.
409 idempotency_in_progress
نعم، بعد ثانية وبالمفتاح Idempotency-Key نفسه. رموز 409 الأخرى: لا.
429 rate_limited و429 too_many_listeners
نعم، بعد Retry-After ثانية (انظر حدود المعدل ).
429 quota_exceeded
لا. استُهلكت حصة الباقة اليومية أو الشهرية، ويعود الإرسال عند params.resetsAt.
503 maintenance
نعم، بعد Retry-After ثانية.
500 و503 وأخطاء الشبكة وانتهاء المهلة
نعم، بفواصل متزايدة وبالمفتاح Idempotency-Key نفسه (انظر منع التكرار ).
تتولى حزمة Node SDK ذلك عنك: تعيد محاولة أخطاء الشبكة و429 و5xx و409 idempotency_in_progress مرتين افتراضيا، مع احترام Retry-After. أما رموز 409 الأخرى فترمى فورًا، ويحمل الحقل retryAfter في الخطأ مدة الانتظار بالثواني. ولا تعيد محاولة 429 quota_exceeded أبدا.
الحالة
code
المعنى
ما العمل
400
validation_failed
حقل أو أكثر غير صالح أو غير معروف، وتسردها errors[].
أصلح كل حقل مذكور.
400
bad_request
المحتوى ليس JSON صالحا، أو طلب مشوه آخر.
أرسل JSON صالحا مع Content-Type: application/json.
400
invalid_cursor
قيمة cursor لم تصدرها الواجهة البرمجية.
مرّر nextCursor كما وصلك تماما.
400
invalid_idempotency_key
في Idempotency-Key أحرف أو طول غير صالح.
استخدم من 1 إلى 255 حرفا من A–Z a–z 0–9 _ - : ..
400
template_invalid
في نص القالب أو الحملة متغير غير معروف أو أقواس شاردة، وتسردها errors[].
استخدم فقط {{first_name}} و{{last_name}} و{{custom.<key>}}.
400
ssrf_blocked
رابط webhook أو التحويل ليس https، أو يشير إلى عنوان خاص أو loopback أو link-local.
استخدم رابط https عاما.
413
payload_too_large
محتوى JSON أكبر من 100 KB، أو ملف الاستيراد أكبر من 5 MB.
أرسل مستلمين أقل في كل طلب، أو قسّم الملف.
الحالة
code
المعنى
ما العمل
401
unauthorized
لا توجد بيانات اعتماد، أو رمز مستخدم غير صالح.
أرسل X-Api-Key.
401
invalid_api_key
المفتاح غير صالح الصيغة أو غير معروف أو ملغى.
تحقق من القيمة، وأنشئ مفتاحا جديدا إن كان ملغى.
401
api_key_expired
انقضت مدة المفتاح.
أنشئ مفتاحا أو دوّره.
403
missing_permission
ينقص المفتاح أو المستخدم صلاحية تحتاجها نقطة النهاية.
أضف الصلاحية المذكورة في المرجع.
403
scope_escalation
حاولت منح مفتاح صلاحيات لا يملكها دورك.
اطلب من مالك أو مسؤول إنشاءه.
403
api_key_not_allowed
نقطة النهاية تقبل مستخدما مسجل الدخول فقط.
نفّذ العملية من البوابة.
403
ip_not_allowed
قائمة عناوين IP للمفتاح لا تشمل الطالب.
أضف العنوان إلى المفتاح.
403
tenant_suspended
المؤسسة موقوفة.
تواصل مع الدعم.
403
forbidden
الإجراء غير مسموح لهذا الطالب.
تحقق من الدور أو نوع المفتاح.
الحالة
code
المعنى
ما العمل
404
not_found
الكائن غير موجود في مؤسستك. كائنات المؤسسات الأخرى تعيد هذا الرمز أيضا.
تحقق من المعرّف ومن مؤسسة المفتاح.
409
contact_exists
توجد جهة اتصال بهذا الرقم.
حدّث جهة الاتصال الموجودة (PATCH /v1/contacts/:id).
409
group_exists
توجد مجموعة جهات اتصال بهذا الاسم.
اختر اسما آخر.
409
template_exists
يوجد قالب بهذا الاسم.
اختر اسما آخر.
409
pool_exists
توجد مجموعة أجهزة بهذا الاسم.
اختر اسما آخر.
409
already_blacklisted
الرقم في القائمة السوداء أصلا.
لا شيء.
409
import_already_started
استُدعي POST /v1/contact-imports/:id/start من قبل.
استعلم عبر GET /v1/contact-imports/:id.
409
invalid_campaign_state
حالة الحملة لا تسمح بهذا الإجراء (مثل تعديل حملة جارية).
تحقق من status أولا.
409
verification_already_approved
قُبل الرمز من قبل.
اعتبر الرقم موثقا ولا تتحقق مجددا.
409
idempotency_in_progress
طلب بهذا المفتاح Idempotency-Key ما زال قيد التنفيذ.
أعد المحاولة قريبا بالمفتاح نفسه.
422
idempotency_key_reused
استُخدم المفتاح مع طلب مختلف خلال آخر 24 ساعة.
استخدم مفتاحا جديدا.
422
campaign_audience_empty
لم تبق أي جهة اتصال في مجموعات الحملة أو وسومها.
أضف جهات اتصال أو غيّر الجمهور.
الحالة
code
المعنى
ما العمل
400
file_required
لا يوجد جزء file في محتوى multipart.
أرسل ملف CSV في الحقل file.
415
unsupported_file_type
ليس CSV، أو ملف ثنائي، أو ليس UTF-8.
احفظه بصيغة CSV UTF-8 وارفعه مجددا.
400
csv_empty
في الملف سطر عناوين ولا صفوف.
أضف صفوفا.
400
csv_too_many_rows
أكثر من 100000 صف.
قسّم الملف.
400
csv_too_many_columns
أكثر من 50 عمودا.
احذف الأعمدة غير المستخدمة.
400
csv_cell_too_long
خلية فيها أكثر من 1000 حرف.
اختصرها.
400
csv_unterminated_quote
خلية بين علامتي تنصيص لا تُغلق.
أصلح علامات التنصيص.
400
csv_duplicate_header
عمودان لهما العنوان نفسه.
أعد تسمية أحدهما.
الحالة
code
المعنى
ما العمل
422
verify_recipient_blacklisted
الرقم في قائمتك السوداء.
أزله من القائمة إن كان ذلك خطأ.
403
verify_country_not_allowed
خدمة التحقق غير مفعلة لدولة الرقم.
اسمح بالدولة من الإعدادات ← التحقق .
403
verify_prefix_blocked
نطاق الرقم محظور بعد حركة غير معتادة.
تواصل مع الدعم لمراجعته.
429
verify_resend_limited
أُرسلت 3 رموز إلى هذا الرقم خلال آخر 10 دقائق.
انتظر Retry-After ثانية.
429
verify_velocity_exceeded
بلغت الحد بالساعة للدولة أو للمؤسسة.
انتظر Retry-After ثانية، أو ارفع الحد من الإعدادات.
تحدد باقتك عدد الهواتف والمقاعد ومفاتيح API ونقاط نهاية webhook المسموح بها، وعدد الرسائل في اليوم وفي الشهر، والميزات المتاحة لك (الباقات ). الطلب المرفوض لا يغير شيئا ولا يرسل شيئا.
الحالة
code
المعنى
ما العمل
403
plan_limit_reached
لا تتسع الباقة لهاتف أو مقعد أو مفتاح API أو نقطة نهاية webhook أخرى، أو يحمل الإرسال مستلمين أكثر مما تسمح به الباقة في الطلب الواحد.
احذف عنصرا لم تعد تستخدمه، أو قسّم الإرسال، أو اطلب تغيير الباقة.
403
feature_not_in_plan
لا تشمل الباقة الميزة: مجموعات الأجهزة أو الإرسال المجدول أو التصدير بصيغة CSV.
اطلب باقة تشملها.
429
quota_exceeded
استُهلكت حصة الرسائل اليومية أو الشهرية.
لا تعد المحاولة في حلقة. يعود الإرسال عند params.resetsAt، ويعرض GET /v1/org/plan القيمتين dayResetsAt وmonthResetsAt.
تحمل هذه الأخطاء params بجانب detail المكتوب بالإنجليزية:
code
params
plan_limit_reached
{ plan, resource, limit }. قيمة resource هي phones أو seats أو apiKeys أو webhooks أو recipients.
feature_not_in_plan
{ plan, feature }. قيمة feature هي pools أو scheduled_sends أو csv_export.
quota_exceeded
{ plan, period, limit, resetsAt }. قيمة period هي day أو month، وresetsAt وقت بصيغة ISO 8601 بتوقيت UTC.
plan هو الاسم المعروض للباقة. ويحمل plan_limit_reached وquota_exceeded أيضا الحقل limit في المستوى الأعلى.
" type " : " https://docs.smsfabric.com/errors/quota_exceeded " ,
" title " : " Too Many Requests " ,
" detail " : " The Free plan allows 50 messages a day. The allowance resets at 00:00 UTC. " ,
" code " : " quota_exceeded " ,
" params " : { " plan " : " Free " , " period " : " day " , " limit " : 50 , " resetsAt " : " 2026-11-20T00:00:00.000Z " },
" requestId " : " req_w9z2c5f8i1l4o7r0u3x6a9d2 "
الحالة
code
المعنى
ما العمل
429
rate_limited
طلبات كثيرة جدا.
انتظر Retry-After ثانية. انظر حدود المعدل .
429
too_many_listeners
لدى مؤسستك 5 بثوث استماع مفتوحة بالفعل.
أغلق واحدا، أو انتظر Retry-After ثانية حتى يحرر البث المفقود مكانه.
500
internal_error
فشل شيء من جهتنا.
أعد المحاولة بفواصل متزايدة، وأرسل requestId إلى الدعم إن استمر.
503
unavailable
خدمة تابعة متوقفة.
أعد المحاولة بفواصل متزايدة.
503
maintenance
SMSFabric في وضع الصيانة. كل المسارات تعيد هذا الرد، بمفتاح أو دونه. يحمل المحتوى detail (الرسالة) وuntil وretryAfterSeconds.
أعد المحاولة بعد Retry-After ثانية، واحتفظ بالرسائل في طابور حتى ذلك الحين.
لن ترى هذه الرموز إلا إذا استدعيت نقاط نهاية تسجيل الدخول بنفسك.
الحالة
code
المعنى
401
invalid_credentials
البريد أو كلمة المرور خطأ، أو الحساب مقفل. الرد واحد في كل الحالات.
401
invalid_2fa_code، mfa_token_invalid
رمز المصادقة الثنائية خطأ، أو انتهت مهلة خطوة الدخول.
401
session_revoked، invalid_token، invalid_refresh_token، refresh_token_reused
انتهت الجلسة. سجّل الدخول مجددا.
400
weak_password، breached_password
كلمة المرور أقصر من 12 حرفا، أو ظهرت في تسريب معروف.
409
email_taken، already_member، last_owner
تعارض في الحساب أو الفريق.
423
account_locked
محاولات فاشلة كثيرة. حاول بعد 15 دقيقة.