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

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>

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

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

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

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

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

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

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

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

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