الأخطاء
الأخطاء تستخدم رموز HTTP القياسية وترجّع دائمًا نفس الشكل:
{ "error": { "type": "invalid_request_error", "code": "missing_template_parameter", "message": "Template \"order_shipped\" is missing the parameter(s): tracking.", "param": "parameters", "doc_url": "https://developers.k-message.kerneltics.com/errors#missing-template-parameter" }}اعتمد على code في كودك. هو جزء من العقد وما يتغيّر اسمه أبدًا؛ الرموز
تنضاف فقط. أما message فمكتوبة لإنسان يقرأ السجل وممكن تتغيّر صياغتها.
وparam يسمّي الحقل الخاطئ إذا كان فيه واحد.
الأنواع
Section titled “الأنواع”type | المعنى | إعادة المحاولة؟ |
|---|---|---|
authentication_error | المفتاح ناقص أو غلط أو منتهي أو ملغي | لا، صلّح المفتاح |
permission_error | المفتاح صحيح لكن ناقصه صلاحية، أو الاشتراك منتهي | لا |
invalid_request_error | فيه شيء غلط في الطلب | لا، صلّح الطلب |
rate_limit_error | طلبات كثيرة | نعم، بعد Retry-After |
api_error | الخطأ من عندنا | نعم |
رموز HTTP
Section titled “رموز HTTP”| الرمز | متى |
|---|---|
400 | المحتوى مو JSON صحيح، أو فيه حقل ما تقبله النقطة |
401 | فشل التوثيق |
403 | صلاحية ناقصة، أو عنوان IP غير مسموح، أو اشتراك متوقف |
404 | ما فيه مورد بهذا المعرّف في منشأتك |
409 | تعارض في منع التكرار، أو جهة اتصال مكررة |
422 | الطلب صحيح شكلاً لكن حقل ناقص أو غلط |
429 | تجاوزت حد الطلبات |
500 | خطأ من عندنا، آمن تعيد المحاولة |
503 | خدمة معتمَد عليها غير متاحة، آمن تعيد المحاولة |
الرمز 404 معناه “مو في منشأتك”، وهذا يغطي المورد اللي ما هو موجود والمورد
اللي يخص عميل ثاني. الاثنين ما ينفرقون بقصد: لو رجّعنا 403 على سجل يخص غيرك
كان أكّدنا إن المعرّف حقيقي، وهذا يسمح لأي أحد يستكشف بيانات بقية العملاء
بالتخمين.
رموز التوثيق
Section titled “رموز التوثيق”missing_credentials
Section titled “missing_credentials”ما أُرسل مفتاح. أرسل Authorization: Bearer km_live_....
invalid_key
Section titled “invalid_key”المفتاح شكله غلط أو ما أُنشئ أصلاً. السبب المعتاد نسخ ناقص.
key_expired
Section titled “key_expired”المفتاح تجاوز تاريخ انتهائه، والرسالة تذكر التاريخ. أنشئ غيره.
key_revoked
Section titled “key_revoked”المفتاح أُلغي نهائيًا. أنشئ غيره.
key_inactive
Section titled “key_inactive”المفتاح معطّل. أحد يقدر يفعّله من لوحة التحكم.
key_wrong_surface
Section titled “key_wrong_surface”استُخدم مفتاح whm_ قديم مع /v1. تلك المفاتيح ما تحمل صلاحيات وغير مقبولة
في الواجهة العامة.
ip_not_allowed
Section titled “ip_not_allowed”المفتاح مقيّد بعناوين محددة والطلب ما جاء من واحد منها. الرسالة تذكر العنوان اللي شفناه، ويستاهل تتأكد منه: خلف NAT أو مزوّد سحابي غالبًا ما يكون اللي تتوقعه.
missing_scope
Section titled “missing_scope”المفتاح صحيح لكن ناقصه الصلاحية اللي تحتاجها هذي النقطة. الرسالة تسمّيها.
subscription_inactive
Section titled “subscription_inactive”اشتراك المنشأة متوقف. الواجهة تتوقف مع لوحة التحكم؛ كلّم اللي يدير حسابك.
رموز الطلب
Section titled “رموز الطلب”invalid_body
Section titled “invalid_body”المحتوى مو JSON صحيح، أو فيه حقل ما تقبله هذي النقطة. الحقول غير المعروفة
تُرفض بدل ما تُتجاهل: كتابة phone بدل to المفروض تقول لك إن اسم الحقل غلط،
مو إن to ناقص من محتوى فيه رقم واضح.
missing_field / invalid_field
Section titled “missing_field / invalid_field”حقل مطلوب ناقص، أو موجود لكن قيمته غلط. param يسمّيه.
unsupported_type
Section titled “unsupported_type”قيمة type مو وحدة من text أو template أو image أو video أو audio
أو document.
template_not_approved
Section titled “template_not_approved”ميتا ما اعتمدت القالب بعد. الرسالة تذكر اسم القالب وحالته. PENDING معناها
انتظر، وREJECTED معناها صلّحه وأعد إرساله من لوحة التحكم.
missing_template_parameter
Section titled “missing_template_parameter”القالب فيه متغيرات ما أرسلتها. الرسالة تعدّد الناقص واللي يتوقعه القالب.
هذا الفحص موجود لأن واتساب ما يسويه: يستبدل المتغيّر الناقص بفراغ، يوصّل الرسالة ناقصة، ويقول إنها نجحت. هذا المكان الوحيد اللي ينمسك فيه.
account_not_found / no_account_configured
Section titled “account_not_found / no_account_configured”قيمة from ما تطابق أي رقم في منشأتك، أو ما فيه رقم موصول أصلاً. نادِ
GET /v1/accounts تشوف الأسماء المتاحة.
marketing_opt_out
Section titled “marketing_opt_out”جهة الاتصال ألغت الاشتراك في الرسائل التسويقية وفئة القالب MARKETING. مرفوض
لأسباب نظامية، مو تفضيل. قوالب الخدمة والتحقق لا تزال توصلها.
contact_exists
Section titled “contact_exists”فيه جهة اتصال بنفس الرقم، والرسالة تتضمن معرّفها. ما ندمج تلقائيًا، لأن تكامل ينشئ نفس العميل مرتين عنده خلل يستاهل يظهر.
idempotency_key_reused
Section titled “idempotency_key_reused”نفس Idempotency-Key استُخدم مع محتوى مختلف، أو الطلب الأول لا يزال شغّال.
campaign_not_startable / campaign_has_no_recipients / campaign_not_editable
Section titled “campaign_not_startable / campaign_has_no_recipients / campaign_not_editable”الحملة في حالة ما تسمح بهذي العملية. الرسالة تذكر الحالة الحالية. المستقبلون ما ينضافون إلا والحملة مسودة أو متوقفة مؤقتًا.
رموز الحد والخادم
Section titled “رموز الحد والخادم”rate_limited
Section titled “rate_limited”خفّف. Retry-After يقول لك كم ثانية تنتظر.
rate_limiter_unavailable
Section titled “rate_limiter_unavailable”ما قدرنا نتحقق من استهلاكك، فرفضنا الطلب بدل ما نمرّره بدون قياس، لأن النقطة اللي يحميها تصرف من رصيدك في واتساب. أعد المحاولة بعد قليل.
upstream_failure
Section titled “upstream_failure”واتساب رفض شيء، عادةً ملف وسائط بصيغة أو حجم ما يقبله.
internal_error
Section titled “internal_error”الخطأ من عندنا. آمن تعيد المحاولة، وأأمن مع Idempotency-Key.