الحالة والدعم

شخّص قبل أن تصعّد

كل فشل مُبلَّغ عنه تقريبًا واحد من خمسة أمور، ولكل منها بصمة يمكن تمييزها:

العَرَض	السبب المرجّح	أين تبحث
401 unauthorized في نداء كان يعمل أمس	مفتاح دُوِّر أو عُطِّل، أو الترويسة مفقودة في أحد مسارات الكود	المصادقة
402 insufficient_balance	رصيد أقل من الحجز اللازم لهذا الإرسال	الحساب والرصيد
طلب واحد يعيد 200 دون أن يُحتسب شيء	فشلت التركيبة كلها؛ وحالة HTTP ليست النتيجة	الفوترة والاسترداد
الطلب نفسه ينجح ويفشل بالتبادل	تحديد معدل، أو إعادة استخدام Idempotency-Key عبر حمولات مختلفة	حدود المعدل، عدم التكرار
مهمة جماعية تبقى في processing ويتوقف last_progress_at عن التحرك	مهمة عالقة فعلًا، لا مهمة بطيئة	حالة المهمة

حالة last_progress_at تستحق أن تُقال بوضوح: الإشارة إلى الفشل ليست الزمن المنقضي، بل طابع زمني متوقف. فمهمة من 500,000 صف قد تستغرق وقتًا طويلًا مشروعًا. أما المهمة التي لم يتحرك last_progress_at فيها فهي مهمة تستحق التصعيد.

ما يجب تضمينه في طلب الدعم

كل حقل أدناه يعيده الـ API، أي أن تضمينه لا يكلّفك شيئًا ويوفّر عليك جولة:

ضمّن	من أين يأتي
request_id	كل استجابة وقت فعلي، بما في ذلك حالات الفشل التي أعادت جسمًا
task_id	كل إرسال جماعي وكل استجابة حالة مهمة
api_key_id	GET /v1/api-key — يحدد المفتاح دون كشفه
حالة HTTP الدقيقة وجسم الاستجابة	سجلاتك أنت؛ وحقل code خاصةً
طابع زمني بتوقيت UTC مع الثواني	سجلاتك أنت
الطلب الذي أرسلته، مع حجب المفتاح	الكود الخاص بك

لا تلصق مفتاح API أبدًا في طلب دعم. فـ api_key_id يحدد المفتاح، والمفتاح نفسه يمنح وصولًا إلى رصيدك.

التواصل بشأن الحوادث

تظهر إشعارات مستوى الحساب — الصيانة المخططة، وتدهور السعة — في لوحة التحكم، وهي أيضًا حيث يقيم الرصيد والسجلات. ويكشف الـ API الظروف نفسها لتكاملك مباشرةً، كرموز أخطاء لا كنصوص:

الرمز	ماذا يعني لتكامل قيد التشغيل
detection_capacity_unavailable	لا سعة الآن. تراجع وأعد المحاولة؛ ولم يُحتسب شيء.
realtime_route_unavailable	لا مسار وقت فعلي متاح. تراجع وأعد المحاولة.
realtime_rate_limiter_unavailable	محدد المعدل نفسه معطّل، فلا يمكن تقرير القبول. أعد المحاولة لاحقًا.
realtime_fact_cache_unavailable	إحدى تبعيات الوقت الفعلي معطّلة. أعد المحاولة لاحقًا.

هذه حالات 503 وكلها في مجموعة “انتظر ثم أعد المحاولة” — راجع رموز الأخطاء للتجميع الكامل، بما في ذلك أي حالات فشل آمنة لإعادة المحاولة بـ Idempotency-Key نفسه.

أهداف الإتاحة ومستويات الدعم المدفوع

تُحدَّد الإتاحة التعاقدية وشروط الخدمة المعوَّضة وأهداف زمن الاستجابة للدعم لكل اتفاق على حدة ولا تُعاد هنا، لأنها تختلف بحسب الخطة، ولأن رقمًا عامًا في صفحة توثيق سيكون خاطئًا لمعظم القرّاء. واتفاقك هو المصدر الموثوق؛ اسأل جهة الاتصال الخاصة بحسابك إن احتجته مكتوبًا.

أين تقف المنصة اليوم

هناك حقيقتان تشغيليتان يمكن التحقق منهما من الخارج ويستحقان المعرفة قبل تسجيل حادثة:

• يُقدَّم الـ API خلف Cloudflare، فمسار الشبكة وإنهاء TLS يشغّلهما Cloudflare لا مضيف مصدر واحد.
• تحمل كل استجابة X-RateLimit-Remaining، فيستطيع العميل الذي يسجّل ترويسات الاستجابة التمييز بين “خنقني حدّي الخاص” و”الخدمة معطّلة” دون سؤال أحد. كما تحمل مجموعتا العام والفحص X-RateLimit-Limit على كل استجابة؛ أما الوقت الفعلي فلا، لأنه يستهلك حاوية رموز لا سقفًا ثابتًا لكل دقيقة.

التالي

• رموز الأخطاء — مجموعات إعادة المحاولة، وهي أسرع جدول فرز
• الأمان — التعامل مع المفتاح، وتدوير مفتاح، وما لا يجب إرساله أبدًا