تخطَّ إلى المحتوى
Documentation

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

API يجب على العملاء اتخاذ القرارات بناءً على رموز حالة HTTP، ورموز الأخطاء الثابتة، ورؤوس الاستجابة. لا تقم بترميز قيم الحصص بشكل ثابت حسب اسم الخطة: يتم تحديد حدود البوابة والخدمة وفقًا للخطة النشطة، وتكوين المسؤول، والملف الشخصي، وسياسة المنتج الحالية.

{
"success": false,
"error": {
"code": "INSUFFICIENT_SCOPE",
"message": "The API key does not have the required scope.",
"status": 403
}
}

يمكن لبعض الخدمات التي يتم الوصول إليها عبر وكيل أن تُرجع غلافًا خاصًا بالخدمة. احرص دائمًا على الاحتفاظ بحالة HTTP ونص الاستجابة في سجلات التشخيص المنظمة، ولكن احجب بيانات الاعتماد وبيانات المستخدم الحساسة.

الحالةالمعنىإجراء العميل
400شكل الطلب أو المعلمة غير صالحةقم بتصحيح الطلب؛ لا تقم بإعادة المحاولة دون تغيير.
401بيانات اعتماد مفقودة أو غير صالحة أو منتهية الصلاحية أو تم إلغاؤهااستبدل بيانات الاعتماد أو جددها.
403تم رفض العملية بسبب سياسة النطاق أو الخدمة أو الدور أو الخطة أو الحصة أو عنوان IP أو الموردافحص رمز الخطأ وتكوين الحساب الحالي.
404لم يتم العثور على المسار أو المورد المطلوبتحقق من الإصدارAPI والمسار والمعرف ووضوح المورد.
409يتعارض هذا الإجراء مع الحالة الحالية للموردقم بتحديث الحالة قبل اتخاذ قرار بشأن إعادة المحاولة.
429تم الوصول إلى الحد الأقصى المباشر للطلبات في الدقيقة أو يوميًاانتظر حتى Retry-After؛ قلل من التزامن أو الاستقصاء.
500وصل الطلب إلى خدمة فشلت بشكل غير متوقعأعد المحاولة فقط إذا كان تكرار العملية آمنًا.
502, 503, 504كان أحد التبعيات أو عناصر التحكم أو الخدمات غير متاح مؤقتًاقم بتطبيق التراجع الأسي المحدود مع التذبذب.

يمكن أن تتضمن رموز أخطاء البوابة MISSING_API_KEY, INVALID_API_KEY, IP_NOT_ALLOWED, INSUFFICIENT_SCOPE, RATE_LIMIT_EXCEEDED, DAILY_LIMIT_EXCEEDED, RATE_LIMIT_UNAVAILABLE, NOT_FOUND, SERVICE_UNAVAILABLE، و INTERNAL_ERROR. يمكن لخدمات الوجهة إرجاع رموز إضافية لمواردها وحصصها الخاصة.

يمكن أن تشمل الطلبات المصادق عليها الناجحة والمرفوضة ما يلي:

X-RateLimit-Limit: <current minute limit>
X-RateLimit-Remaining: <requests left in the current minute window>
X-RateLimit-Reset: <Unix timestamp>
X-DailyLimit-Limit: <current daily limit>
X-DailyLimit-Remaining: <requests left in the current daily window>
Retry-After: <seconds>

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

استراتيجية إعادة المحاولة

Section titled “استراتيجية إعادة المحاولة”

استخدم التراجع الأسي المحدود مع التذبذب للحالات المؤقتة. تبدأ التسلسلات العملية من حوالي ثانية واحدة وتزداد حتى تصل إلى تأخير أقصى معتدل. احترم القيمة الأكبر Retry-After القيمة الأكبر عند وجودها.

أعد المحاولة فقط عندما تكون العملية آمنة:

  • GET عادةً ما تكون إعادة محاولة الطلبات آمنة.
  • قد تكون عملية إنشاء أو إرسال أو تحديث فاشلة قد اكتملت قبل فشل الاتصال . تأكد من حالة المورد قبل إعادة المحاولة.
  • لا تقم بإعادة المحاولة 400, 401، أو معظم 403 الاستجابات دون تغيير الطلب أو بيانات الاعتماد.
  • حدد الحد الأقصى لعدد المحاولات واعرض رسالة خطأ مفيدة عند بلوغ هذا الحد.

تقليل حركة المرور غير الضرورية

Section titled “تقليل حركة المرور غير الضرورية”
  • قم بتخزين استجابات الصلاحيات أو البيانات الوصفية للقراءة فقط في ذاكرة التخزين المؤقت لفترة قصيرة مناسبة بدلاً من التحقق منها عند كل تفاعل مع واجهة المستخدم.
  • يفضل webhooks للاطلاع على الأحداث المدعومة.
  • دمج الطلبات المتطابقة من نفس حمل العمل.
  • قم بتقسيم المجموعات الكبيرة إلى صفحات وتجنب التزامن غير المحدود.
  • استخدم CLI’s --json الإخراج في البرامج النصية بدلاً من إصدارAPI طلبات مكررة للتنسيق.

تشخيص الرفض غير المتوقع

Section titled “تشخيص الرفض غير المتوقع”
  1. الاستدعاء GET /v1/auth/whoami لتأكيد الهوية والمفتاح النشطين.
  2. الاستدعاء GET /v1/auth/quota للحصول على اللقطة الحالية لحصة البوابة.
  3. تأكد من أن المفتاح له النطاق المطلوب للمسار.
  4. تأكد من تمكين الخدمة الوجهة للملف الشخصي النشط.
  5. تحقق من أذونات الدور والمؤسسة في الخدمة الوجهة.
  6. سجل الحالة ورمز الخطأ ورؤوس الاستجابة ووقت الطلب قبل الاتصال بـ CHAMPREP الدعم.