مرجع رموز الأخطاء

حين يستدعي الشريط أو كودك واجهة أرقام٣٦٠ البرمجيّة، يعود الخطأ بحالة HTTP ومحتوى JSON يصف فيه الحقل error المشكلة. إليك الأخطاء الأكثر شيوعًا وطريقة التعامل مع كلّ منها.

أخطاء مفتاح API

• 401 "API key required" — لم يُرسَل أيّ مفتاح. أرسله في الترويسة X-API-Key أو بالصيغة Authorization: Bearer YOUR_API_KEY. وفي موقعك، تأكّد أنّ وسم script يحمل data-key="YOUR_API_KEY".
• 401 "Invalid API key" — المفتاح لا يطابق أيّ مفتاح فعّال في حسابك؛ فربّما نُسخ خطأً، أو أُلغي، أو أُعيد إنشاؤه. انسخ المفتاح الحالي من لوحة التحكم.
• 401 "API key expired" — انتهت صلاحية المفتاح. أنشئ مفتاحًا جديدًا.
• 403 "Secret key required" (الرمز API_KEY_SCOPE_REQUIRED) — أُرسل مفتاح الأداة العامّ في موضع يتطلّب رمز الموقع السرّي (Site Token) الذي يبدأ بـ ciq_sk_، مثل لوحة التحكم داخل إضافة WordPress.
• 403 "Subscription inactive" أو "Trial expired" — تُرجعه الميزات المدفوعة حين تنتهي فترتك التجريبية أو اشتراكك. ويستمرّ تسجيل الموافقات وتحميل الشريط في الحالتين، فاختر باقة لاستعادة بقيّة الميزات.

أخطاء الطلب والنطاق

• 400 "Missing required fields: consent, domain" — يجب أن يتضمّن سجلّ الموافقة الحقلين معًا.
• 400 "Invalid consent field" — لا يقبل الحقل consent إلا true أو false لكلّ من necessary و analytics و marketing و functional و preferences.
• 400 "Invalid domain format" — يجب أن يكون النطاق نصًّا لا يتجاوز 256 حرفًا.
• 403 "Domain not registered" — الموقع الذي يرسل الموافقة ليس من نطاقات حسابك. أضفه من الموافقة ← النطاقات، علمًا أنّ النطاق مع www وبدونها يُعدّان موقعًا واحدًا.
• 403 "API key bundleId does not match the request domain" — استُخدم مفتاح تطبيق جوّال مع معرّف حزمة (bundle ID) لتطبيق آخر.

حدود المعدّل (429)

تعني الحالة 429 Too Many Requests بلوغ أحد الحدود. فتسجيل الموافقات محدود بـ 100 طلب في الدقيقة من عنوان IP واحد، وبعدد من الطلبات كلّ 15 دقيقة لحسابك يتوقّف على باقتك: 500 في الباقة المجانية، و2,000 في Pro، و50,000 في Managed و Agency. كما تسمح الواجهة البرمجيّة عمومًا بـ 1,500 طلب كلّ 15 دقيقة من عنوان IP واحد. ولأنّ شريط كلّ زائر يتّصل من عنوان IP الخاصّ به، فحدود العنوان الواحد تخصّ غالبًا عمليّات الربط من الخادم. وتتضمّن الاستجابات على هذه المسارات الترويسات RateLimit-Limit و RateLimit-Remaining و RateLimit-Reset، وتحمل استجابة 429 أيضًا الترويسة Retry-After بالثواني.