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

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

ارجع إليها عندما يعيد استدعاء كان يعمل بالأمس كوداً لا تعرفه، أو عندما تقدّر عدد الطلبات التي يستطيع تطبيقك تنفيذها، أو عندما تريد معرفة ما سيكلّفه استدعاء بالضبط قبل أن تطلقه.

حدود المعدل

تُضبط الحدود لكل مفتاح، بحسب وضع الوصول:

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

يبدأ المفتاح الحي الجديد عند basic دون أي خطوة موافقة. أما premium وpro فيُسندان من Cognivo، وحدود partner وenterprise تُضبط بحسب الاتفاق. تعود ترويسات RateLimit-* القياسية مع كل استدعاء، فتستطيع رؤية ميزانيتك المتبقية دون تخمين. وعندما تنفد الميزانية تحصل على 429 rate_limited مع ترويسة Retry-After تخبرك متى تعيد المحاولة.

مراقبة استخدامك

سجّل الدخول إلى التطبيق اللامركزي، وافتح Account في الشريط الجانبي الأيسر، واختر Developers، ثم افتح علامة التبويب Usage.

علامة تبويب الاستخدام في صفحة المطورين، معروضة لمفتاح لم يُستخدم بعد.تكبير الصورة

يبدّل محدّد النافذة في الأعلى بين Last 24 hours وLast 7 days وLast 30 days. وبجانبه، تعرض شارة رصيد أرصدتك وأخرى تعرض طبقة المعدل والحد الساعي المطبَّق على مفاتيحك. وأسفل ذلك، تقسّم خمسة عدّادات النافذة إلى Requests وSuccessful وErrors وRate limited وCredits used، وتقسّم بطاقة Outcome breakdown النافذة نفسها بثلاث طرق.

Quoted vs charged هي اللوحة التي تقرؤها قبل أن تقلق بشأن فاتورة. وبعبارة المنتج نفسه، "Quoted is the list price. Charged is what actually came out of your balance." الرقمان ليسا متطابقين دائماً، لأن الاستدعاءات الفاشلة والمرفوضة والإجابات الفارغة بصدق تُسعَّر لكن لا تُحصَّل أبداً.

Request history تسرد الاستدعاءات الفردية ويمكن تصفيتها بالمفتاح ونقطة النهاية والحالة. وهناك حالتان فارغتان تعنيان أمرين مختلفين. "No requests match these filters." تعني أن استدعاءات موجودة في هذه النافذة لكن لا شيء منها يطابق ما صفّيت به، فوسّع المرشّحات. و"No usage in this window yet." تعني أن أي استدعاء من أي من مفاتيحك لم يصل في هذه النافذة إطلاقاً. وليست أي منهما خطأ، ولا تعني أي منهما أن استدعاءً ضاع. إذا كنت تتوقع حركة وترى صفراً، فتحقق من أن تطبيقك يستخدم المفتاح الذي تظنه ووسّع النافذة.

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

HTTP	error	المعنى
400	bad_request / invalid_chain / invalid_address / invalid_wallet / invalid_token	مدخلات مشوّهة. يجب أن يكون chain هو eth أو base أو bsc، ويجب أن تكون العناوين 0x زائد 40 حرفاً ست عشرياً.
401	missing_api_key	لم يُقدَّم أي X-API-Key أو رمز Bearer.
401	invalid_api_key	مفتاح غير معروف، أو ليس مفتاح Cognivo v2.
402	payment_required	لا توجد أرصدة Cognivo كافية لهذا الاستدعاء. لم تُحصَّل أي رسوم.
403	access_required	مفتاح قديم للبيانات الوصفية فقط حاول تنفيذ استدعاء حي.
403	sandbox_limited	مفتاح sandbox (cogv_test_) حاول تنفيذ استدعاء ذكاء حي.
403	trial_expired	انتهى المخصّص التجريبي الاختياري للمفتاح.
403	trial_exhausted	استُهلك المخصّص التجريبي الاختياري للمفتاح بالكامل.
403	endpoint_denied	ترتيب وصول المفتاح لا يغطي هذه نقطة النهاية.
403	chain_denied	المفتاح محصور بشبكات معينة وهذا الطلب سمّى شبكة مختلفة. مرفوض قبل أي استدعاء أعلى السلسلة وقبل استخدام أي مخصّص.
403	key_expired	مرّ تاريخ انتهاء المفتاح. وهو مرفوض في كل مكان، بما في ذلك GET /v1/api/me.
403	suspended_key	المفتاح معلَّق ولا يستطيع التنفيذ. وتعرض البوابة السبب.
403	revoked_api_key	أُلغي المفتاح أو دُوِّر عنه.
403	project_disabled	المشروع المالك معلَّق أو مؤرشف.
403	scope_denied	المفتاح يفتقر إلى النطاق الذي تحتاجه هذه نقطة النهاية.
403	origin_denied	قائمة سماح للأصول أو لعناوين IP مضبوطة على المفتاح وهذا الطلب لم يطابقها.
404	public_api_disabled	الواجهة البرمجية العامة مطفأة مؤقتاً.
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، وتحقق من أن لا وكيلاً يزيل الترويسة.
• 401 invalid_api_key. يجب أن يبدأ المفتاح بـ cogv_live_ أو cogv_test_. انسخ المفتاح كاملاً دون مسافات محيطة. وإذا فقدت الأصلي، فدوّر المفتاح في البوابة واستخدم الجديد.
• 402 payment_required. اشحن رصيدك في صفحة فوترة Cognivo، ثم أعد المحاولة. لم تُحصَّل أي رسوم. وتعرض GET /v1/api/me رصيدك الحالي.
• 403 revoked_api_key. خذ أحدث مفتاح من البوابة. القديم لن يعمل أبداً مرة أخرى.
• 403 scope_denied. المفتاح يعمل لكنه يفتقر إلى النطاق الذي تحتاجه هذه نقطة النهاية، مثل security:read لـ wallet/approvals. راجع المصادقة ومفاتيح API.
• 403 origin_denied. استدعِ من أصل أو IP مدرج في قائمة السماح، أو امسح القوائم على المفتاح.
• 403 access_required. هذا مفتاح قديم للبيانات الوصفية فقط من قبل الفوترة ذاتية الخدمة. أنشئ مفتاحاً حياً جديداً في البوابة.
• 403 sandbox_limited. مفاتيح sandbox للاختبار ولا تستطيع تشغيل الذكاء الحي. أنشئ مفتاحاً حياً.
• 403 chain_denied. تحقق من allowed_chains في GET /v1/api/me. وجود null هناك يعني عدم وجود تقييد. لم تُحصَّل أي رسوم.
• 403 trial_expired أو trial_exhausted. انتهى مخصّص التقييم الاختياري. لا تحتاج إلى تجربة، فانتقل إلى مفتاح حي عادي.
• 403 endpoint_denied. ترتيبك يغطي نقاط نهاية أخرى لكن ليس هذه. اطلب إدراجها.
• 403 suspended_key. تعرض البوابة السبب. تواصل مع الدعم من التطبيق اللامركزي مع request_id إذا لم يكن واضحاً.
• 429 rate_limited. احترم ترويسة Retry-After وأضف طابوراً في جانب العميل مع تراجع تدريجي، أو اسأل عن حد أعلى.
• 400 invalid_chain. استخدم eth أو base أو bsc. الأسماء مثل ethereum ومعرّفات الشبكات الرقمية غير مقبولة.
• 400 invalid_address أو invalid_wallet أو invalid_token. أرسل عنواناً كاملاً 0x زائد 40 حرفاً ست عشرياً. لا تحل الواجهة البرمجية أسماء ENS ولا رموز التوكنات.
• 422 insufficient_data. ليس انقطاعاً وليس خطأك. عملت الأداة لكنها لم تستطع تأصيل إجابة عادلة، مثلاً wallet/pnl على محفظة بلا صفقات مسعّرة في ذلك التوكن. يعني ذلك أن Cognivo لم يستطع التحقق من الإجابة، لا أن الإجابة صفر. ولا تُحصَّل عليك رسوم أبداً مقابل 422.
• 404 public_api_disabled. الواجهة البرمجية العامة مطفأة مؤقتاً. هذا ليس عنوان URL خاطئاً، فأعد المحاولة لاحقاً.

الأرصدة والفوترة

المفاتيح الحية خدمة ذاتية. لا يوجد طلب ولا اشتراك. المفتاح الحي الجديد يعمل فوراً، وكل استدعاء ناجح يخصم سعر تلك نقطة النهاية بالأرصدة من رصيد أرصدة Cognivo الخاص بـ مالك المشروع، وهي الأرصدة نفسها التي تستخدمها المحادثة والتطبيق اللامركزي. ويحصل كل حساب على 5 أرصدة مجانية يومياً، وتُعاد ضبطها عند منتصف الليل بتوقيت UTC. تحصيل الرسوم على استدعاءات Developer API متوقف اليوم، لذا لا يخصم الاستدعاء الناجح أي رصيد ولا يتغير رصيدك.

سعر كل نقطة نهاية بالأرصدة مطبوع بجانبها في علامة التبويب Endpoints بصفحة Developers، ونقاط النهاية المجانية موسومة بـ Free هناك. اقرأ السعر من البوابة بدلاً من تثبيته في الشيفرة.

• الاستدعاءات الفاشلة لا تُحصَّل عليها رسوم أبداً. الأخطاء والمهل المنتهية والاستدعاءات المرفوضة وحدود المعدل لا تكلّف شيئاً.
• الاستدعاء الناجح يُحصَّل مرة واحدة بالضبط، لذا فإعادة المحاولة آمنة.
• النتائج الفارغة بصدق مجانية. الرمز 422، وقائمة wallet/approvals الفارغة، إجابتان صحيحتان ولا تُحصَّل عليهما رسوم.
• نفاد الأرصدة يعطيك 402 payment_required دون تحصيل أي شيء. اشحن رصيدك في التطبيق اللامركزي، ثم أعد المحاولة.
• مفاتيح Sandbox (cogv_test_) لا تُحصَّل عليها رسوم أبداً ولا تستطيع تشغيل الذكاء الحي.
• المفاتيح المعلَّقة والمشاريع المعطَّلة لا تستطيع تنفيذ أي شيء ولا تُحصَّل عليها رسوم أبداً.
• Enterprise هو مسار الطلب للتسعير المخصص والحدود المخصصة والحجم الكبير، وتطلبه من التطبيق اللامركزي.

قراءة النتائج بصدق

تصف نتائج الواجهة البرمجية ما فحصه Cognivo وما وجده على السلسلة. النتيجة النظيفة ليست دليلاً على أن توكناً أو محفظة آمنة، والنتيجة الموسومة بعلم ليست دليلاً على احتيال. والحقل المفقود أو غير المتاح يعني أن Cognivo لم يستطع التحقق من ذلك العنصر، لا أنه لا يوجد شيء هناك. عامل كل استجابة كمدخل واحد في بحثك الخاص.

الخطوات التالية

ابحث عن المعاملات والنطاقات وأمثلة الاستجابات في مرجع نقاط النهاية، وأحكِم مفاتيحك عبر المصادقة ومفاتيح API، أو اطّلع على كيفية عمل الأرصدة في بقية المنتج في الفوترة والأرصدة.