حدود المعدل والأخطاء والفوترة

حدود المعدل

الحدود لكل مفتاح، بحسب نمط الوصول:

نمط الوصول	الحد
المدفوع الحي: basic (الافتراضي لكل مفتاح حي جديد)	1,000 طلب/ساعة
المدفوع الحي: premium (يخصصه المسؤول)	5,000 طلب/ساعة
المدفوع الحي: pro (يخصصه المسؤول)	15,000 طلب/ساعة
الشراكة / المؤسسي	يضبطه المسؤول
أي مفتاح sandbox من نوع cogv_test_	25 طلباً/ساعة و100/يوم و1/ثانية
سطح البيانات الوصفية (health وme وdiscover) بأي مفتاح صالح	60 طلباً/ساعة و1/ثانية

يبدأ المفتاح الحي الجديد عند basic (1,000 طلب/ساعة) دون أي خطوة موافقة؛ ويخصص المسؤول فئتي premium و pro، وتُضبط حدود الشراكة والمؤسسي بحسب الاتفاقية. تُعاد ترويسات RateLimit-* القياسية؛ وعند الاستنفاد تحصل على 429 rate_limited مع ترويسة Retry-After تخبرك متى تعيد المحاولة.

أكواد الأخطاء

HTTP	error	المعنى
400	bad_request / invalid_chain / invalid_address / invalid_wallet / invalid_token	مدخلات مشوهة؛ يجب أن تكون السلسلة eth أو base أو bsc؛ والعناوين يجب أن تكون 0x + 40 حرفاً سداسي عشرياً
401	missing_api_key	لم تُقدَّم أي X-API-Key (أو Bearer)
401	invalid_api_key	مفتاح غير معروف أو ليس مفتاح Cognivo v2
402	payment_required	لا توجد أرصدة Cognivo كافية لهذا الاستدعاء. اشحن رصيدك في صفحة الفوترة لحساب Cognivo الخاص بك وحاول مجدداً. لم يُحصَّل شيء؛ والاستدعاءات الفاشلة لا يُحصَّل عليها شيء أبداً
403	access_required	حاول مفتاح قديم مقتصر على البيانات الوصفية إجراء استدعاء حي - أنشئ مفتاحاً حياً جديداً بخدمة ذاتية للانتقال إلى الدفع حسب الاستخدام
403	sandbox_limited	حاول مفتاح Sandbox (cogv_test_) إجراء استدعاء ذكاء حي؛ فمفاتيح sandbox لا يمكنها تشغيل الذكاء الحي
403	trial_expired	انتهت صلاحية المخصص التجريبي الاختياري للمفتاح
403	trial_exhausted	استُنفد المخصص التجريبي الاختياري للمفتاح بالكامل
403	endpoint_denied	ترتيب وصول المفتاح لا يغطي نقطة النهاية المحددة هذه
403	suspended_key	المفتاح معلّق ولا يمكنه التنفيذ؛ وتعرض البوابة السبب
403	revoked_api_key	المفتاح أُبطل أو دُوِّر بعيداً
403	project_disabled	المشروع المالك معلّق أو مؤرشف
403	scope_denied	يفتقر المفتاح إلى النطاق الذي تحتاجه نقطة النهاية هذه
403	origin_denied	قائمة سماح Origin/IP مضبوطة على المفتاح ولم تتطابق
404	public_api_disabled	الـ API العامة معطّلة مؤقتاً
422	insufficient_data (وما شابهها)	الأداة عملت لكنها لم تستطع توثيق نتيجة عادلة - لا يُحصَّل عليك شيء
429	rate_limited	استُنفدت ميزانية المعدل؛ وتحمل الاستجابة ترويسة Retry-After
500	internal_error	فشل غير متوقع - أرفق request_id عند التواصل مع الدعم
503	pricing_mismatch / billing_unavailable / billing_commit_failed / unavailable	عثرة نادرة في الفوترة أو في تبعية ما - لم يُحصَّل شيء، ببساطة أعد المحاولة

تحمل كل استجابة request_id (وكذلك meta.request_id عند النجاح). احتفظ به؛ يمكن للدعم تتبّع الاستدعاء منه.

الأخطاء الشائعة وكيفية إصلاحها

• 401 missing_api_key - لم يصلنا المفتاح قط. أرسله في الترويسة X-API-Key (بالاسم الدقيق) أو كـ Authorization: Bearer YOUR_API_KEY، وتحقق من أن وكيلاً (proxy) أو إطار عمل لا يحذف الترويسة.
• 401 invalid_api_key - المفتاح غير معروف. يجب أن يبدأ بـ cogv_live_ أو cogv_test_؛ تأكد من أنك نسخت المفتاح كاملاً دون مسافات محيطة. إذا فقدت الأصل، فقم بتدوير المفتاح في البوابة واستخدم الجديد.
• 402 payment_required - لا توجد أرصدة Cognivo كافية لهذا الاستدعاء. اشحن رصيدك في صفحة الفوترة لحساب Cognivo الخاص بك وحاول مجدداً؛ لم يُحصَّل شيء، والاستدعاءات الفاشلة لا يُحصَّل عليها شيء أبداً. تعرض GET /v1/api/me رصيدك الحالي.
• 403 revoked_api_key - هذا المفتاح أُبطل أو دُوِّر بعيداً. خذ أحدث مفتاح من البوابة؛ فالقديم لن يعمل مجدداً أبداً.
• 403 scope_denied - المفتاح يعمل، لكنه يفتقر إلى النطاق الذي تحتاجه نقطة النهاية هذه (مثلاً security:read لـ wallet/approvals). عدّل نطاقات المفتاح أو أنشئ مفتاحاً بالنطاق الصحيح؛ انظر المصادقة ومفاتيح API.
• 403 origin_denied - المفتاح لديه قائمة سماح Origin أو IP وهذا الطلب جاء من مكان آخر. استدعِ من أصل/عنوان IP مسموح به، أو امسح القوائم من المفتاح.
• 403 access_required - هذا مفتاح قديم مقتصر على البيانات الوصفية من قبل عهد فوترة الخدمة الذاتية. أنشئ مفتاحاً حياً جديداً في البوابة؛ يعمل فوراً، بالدفع حسب الاستخدام، دون أي خطوة موافقة.
• 403 sandbox_limited - حاول مفتاح Sandbox (cogv_test_) إجراء استدعاء ذكاء حي. مفاتيح Sandbox مخصصة للعروض التوضيحية والاختبار المحدود فقط؛ أنشئ مفتاحاً حياً، فهو يعمل فوراً.
• 403 trial_expired / trial_exhausted - انتهى مخصص التقييم الاختياري لديك (زمناً أو استخداماً). أنت لا تحتاج إلى وصول تجريبي: انتقل إلى مفتاح حي عادي بالدفع حسب الاستخدام، أو اسأل عن المؤسسي للأحجام الكبيرة.
• 403 endpoint_denied - يغطي ترتيب وصولك نقاط نهاية أخرى لكن ليس هذه (الوصول الخاص بنقاط نهاية بعينها شائع في ترتيبات الشراكة/المؤسسات). اطلب إدراج نقطة النهاية هذه.
• 403 suspended_key - المفتاح معلّق ولا يمكنه التنفيذ. تعرض البوابة السبب؛ تواصل مع الدعم من الـ dApp مع request_id الخاص بك إذا كان الأمر غير واضح.
• 429 rate_limited - استنفدت ميزانية هذا المفتاح. التزم بترويسة Retry-After، أو أضف طوابير من جهة العميل مع تراجع (backoff)، أو اسأل عن حد أعلى. تذكر أن مفاتيح sandbox من نوع cogv_test_ محدودة بـ 25 طلباً/ساعة و100/يوم و1/ثانية؛ وسطح البيانات الوصفية محدود بـ 60/ساعة مع حد اندفاع قدره 1/ثانية.
• 400 invalid_chain - يجب أن تكون chain هي eth أو base أو bsc. الأسماء مثل ethereum أو معرّفات السلاسل الرقمية مثل 8453 غير مقبولة.
• 400 invalid_address / invalid_wallet / invalid_token - أرسل عنواناً كاملاً بصيغة 0x + 40 حرفاً سداسي عشرياً. لا تحل الـ API أسماء ENS ولا رموز التوكنات.
• 422 insufficient_data - ليس انقطاعاً وليس خطأك: الأداة عملت لكنها لم تستطع توثيق إجابة عادلة (مثلاً wallet/pnl على محفظة بلا صفقات مسعّرة في ذلك التوكن). لا يُحصَّل عليك أبداً مقابل 422؛ جرّب محفظة/توكناً مختلفاً أو سؤالاً أوسع.
• 503 pricing_mismatch / billing_unavailable / billing_commit_failed - عثرة فوترة نادرة. لم يُحصَّل شيء؛ ببساطة أعد الاستدعاء.
• 404 public_api_disabled - الـ API العامة معطّلة مؤقتاً، وليس عنوان URL خاطئاً. حاول مجدداً لاحقاً أو راجع قناة الإعلانات.

الفوترة والأرصدة وشحن الرصيد

المفاتيح الحية خدمة ذاتية وبنظام الدفع حسب الاستخدام. لا طلب تقديم، ولا اشتراط وصول تجريبي، ولا اشتراك: المفتاح الحي الجديد يعمل فوراً، وكل استدعاء ناجح يخصم سعر نقطة النهاية بالأرصدة من رصيد أرصدة Cognivo الخاص بـ مالك المشروع (نفس أرصدة Chat والـ dApp).

• الاستدعاءات الفاشلة لا يُحصَّل عليها شيء أبداً. الأخطاء والمهلات والاستدعاءات المرفوضة وحدود المعدل لا تكلّف شيئاً.
• الاستدعاء الناجح يُحصَّل مرة واحدة بالضبط. الإرسالات المكررة لنفس العملية لا يمكن أن تُحصَّل عليك مرتين، لذا فإن إعادة المحاولة آمنة.
• النتائج الفارغة النزيهة مجانية. استجابة 422 (مثلاً wallet/pnl بلا صفقات مسعّرة) والقائمة الفارغة من wallet/approvals إجابتان صحيحتان ولا يُحصَّل عليهما شيء.
• نفدت أرصدتك؟ تحصل على 402 payment_required ولا يُحصَّل شيء. اشحن رصيدك في صفحة الفوترة لحساب Cognivo الخاص بك في الـ dApp، ثم أعد المحاولة. تعرض GET /v1/api/me رصيد credits_balance وإرشادات top_up.
• مفاتيح Sandbox (cogv_test_) لا يُحصَّل عليها شيء أبداً: فهي مخصصة للعروض التوضيحية المحدودة واختبار التكامل ولا يمكنها تشغيل الذكاء الحي.
• التجريبي (Trial) مخصص تقييم اختياري يمنحه مسؤول - غير مطلوب للاستخدام المدفوع العادي. الشراكة (Partner) يديرها المسؤولون. المؤسسي (Enterprise) هو مسار الطلب للتسعير المخصص والحدود المخصصة والأحجام الكبيرة - اطلبه من الـ dApp.
• المفاتيح المعلّقة والمشاريع المعطّلة لا يمكنها تنفيذ أي شيء ولا يُحصَّل عليها شيء أبداً؛ وتعرض البوابة السبب.

أسعار الأرصدة لكل استدعاء ناجح:

نقطة النهاية	الأرصدة لكل استدعاء ناجح
intel/liquidity	2
intel/risk	2
wallet/approvals	2
intel/why-down	3
intel/team-wallets	5
wallet/exact-movements	5
wallet/pnl	10
health وme	مجانية
discover	مجانية، مع حد معدل مشدود

ليست نصيحة مالية

نتائج الـ API هي إشارات ذكاء على السلسلة، وليست نصيحة استثمارية، وغياب علم أحمر ليس دليلاً على الأمان. قم دائماً ببحثك الخاص.