أخطاء API وماذا تعني

ماذا تعني عادةً كل حالة HTTP من واجهة برمجة تطبيقات Didit عمليًا - 401 و403 المتعلقة بالمفاتيح والصلاحيات، ومشكلات الرصيد من نوع 402، وحدود المعدل 429، وكيفية قراءة نص الخطأ.

بقلم دعم Didit · آخر تحديث 19 أغسطس 2026

#اقرأ نص الاستجابة أولًا

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

123

1. المفتاح المعطَّل أو الخاص بتطبيق خاطئ هو السبب المعتاد لخطأ 401.
2. يؤكد آخر استخدام ما إذا كان المفتاح الذي تظن أنك ترسله هو الذي يصل فعلًا.
3. دوِّر السر إذا كان أحد المفاتيح قد تسرّب - خطأ 401 أفضل من اختراق.

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

#ماذا تعني كل حالة عادةً

#401 مقابل 403 - الفرق الذي يوفر عليك الوقت

401 تعني أن المفتاح لم يُقبل إطلاقًا. تحقق من أنك ترسل x-api-key، وأن القيمة لا تحتوي على مسافات أو علامات اقتباس زائدة، وأنك لم تلصق سرّ توقيع webhook بدلًا من مفتاح API - فهما شيئان مختلفان وهذا خطأ شائع.

403 تعني أن المفتاح صالح لكن هذا الاستدعاء غير مسموح به. ثلاثة أسباب، بالترتيب:

1. عدم تطابق البيئة. الحقول الخاصة بـ sandbox فقط (مثل sandbox_scenario) تُرفض في تطبيق مباشر، والعكس صحيح. البيئتان المباشرة وsandbox تطبيقان منفصلان بمفاتيح منفصلة.
2. صلاحية مفقودة. بعض العمليات تحتاج صلاحيات لا يملكها مفتاحك أو دورك. إذا احتجت صلاحيات إنشاء وإدارة الجلسات ولا تملكها، فذلك طلب يُوجَّه إلى الدعم لا إصلاح في الشيفرة.
3. ميزة غير مفعّلة. بعض الإمكانيات تُوفَّر لكل منظمة على حدة. خطأ 403 على ميزة تظن أنه يجب أن تملكها يستحق السؤال عنه قبل إعادة كتابة الاستدعاء.

#404 رغم أنه يجب أن يكون موجودًا

إذا أعطت جلسة أو سير عمل خطأ 404 وأنت متأكد من وجوده، فالسبب المعتاد هو أنه موجود ضمن تطبيق مختلف عن التطبيق الذي وثّقت هويتك من خلاله بالمفتاح. الموارد مرتبطة بتطبيقها، ولا يمكن لمفتاح من التطبيق A رؤية جلسات التطبيق B.

#أخطاء الرصيد

الاستدعاء الذي يفشل لعدم كفاية الرصيد ليس مشكلة في الشيفرة. سير العمل يحتوي على ميزة مدفوعة ورصيدك لا يغطيها. هذا أكثر تقرير شائع من نوع "واجهة برمجة التطبيقات معطّلة"، والسبب يكاد يكون دائمًا العلامة البيضاء، أو AML، أو NFC في سير عمل كان من المتوقع أن يكون مجانيًا. انظر إصلاح خطأ «رصيد غير كافٍ».

#حدود المعدل 429

تُطبَّق الحدود لكل معرِّف - مفتاح x-api-key الخاص بك، أو عنوان IP للعميل إذا لم يُرسَل مفتاح - بعداد مستقل لكل نطاق على نافذة متحركة مدتها 60 ثانية.

الإعدادات الافتراضية العامة:

بعض نقاط النهاية عالية الأثر لديها حدود أكثر صرامة بالإضافة إلى الحد العام، وأول نطاق يتجاوز عداده هو الذي يُعيد 429. الجدول الكامل: حدود المعدل.

تعامل مع 429 بتأخير تصاعدي مع عشوائية. حلقة إعادة محاولة ضيقة أمام حد معدل تزيد المشكلة سوءًا ويمكن أن تُبقيك مقيّدًا إلى أجل غير مسمى.

#رموز التفصيل على مستوى الميزة

بخلاف حالات HTTP، تُعيد الفحوصات الفردية رموز تفصيل خاصة بها لمشكلات على مستوى المزوّد - على سبيل المثال تكامل سجل لا يملك وصولًا إلى منتج معيّن في بلد معيّن. عندما تحصل على أحدها، يسمّي الرمز الموقف بدقة، لذا اقتبسه عند السؤال عنه.

إذا حذفت استجابة رمز تفصيل كنت تتوقعه من الكتالوج، فذلك يستحق الإبلاغ عنه بدلًا من الالتفاف حوله - الرمز المفقود فجوة حقيقية، ويجعل المشكلة نفسها أصعب على الشخص التالي.

#الاستجابات الفارغة ليست نجاحًا

فحص مدعوم بمزوّد يُعيد جسمًا فارغًا ليس مثل نتيجة نظيفة. عامل "لا بيانات" كحالة قائمة بذاتها في شيفرتك بدلًا من ربطها بنجاح - خصوصًا لعمليات التحقق من قواعد البيانات وفحص المحافظ، حيث يمكن أن تتشابه خدمة غير مزوَّدة مع عدم تطابق حقيقي من الخارج.

#اختبار مسارات الخطأ

يفرض sandbox أخطاء محددة بشكل حتمي، وهي الطريقة العاقلة الوحيدة لاختبار معالجة الأخطاء لديك. انظر الاختبار في sandbox.