تخطَّ إلى المحتوى

الأخطاء

عندما يفشل طلب، ترد الواجهة البرمجية بحالة HTTP ومحتوى من نوع application/problem+json (RFC 9457). اعتمد في منطقك على code لا على detail: الرموز ثابتة، أما النص المقروء فقد يتغير.

{
"type": "https://docs.smsfabric.com/errors/validation_failed",
"title": "Bad Request",
"status": 400,
"detail": "The request is invalid",
"code": "validation_failed",
"errors": [
{ "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_…"}
الحالة إعادة المحاولة؟
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 أبدا.

الطلب والتحقق من المدخلات

Section titled “الطلب والتحقق من المدخلات”
الحالة 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",
"status": 429,
"detail": "The Free plan allows 50 messages a day. The allowance resets at 00:00 UTC.",
"code": "quota_exceeded",
"limit": 50,
"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 ثانية، واحتفظ بالرسائل في طابور حتى ذلك الحين.

تسجيل الدخول (البوابة ورموز المستخدم)

Section titled “تسجيل الدخول (البوابة ورموز المستخدم)”

لن ترى هذه الرموز إلا إذا استدعيت نقاط نهاية تسجيل الدخول بنفسك.

الحالة 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 دقيقة.