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

يستخدم كل فشل في API صيغة JSON ويتضمن معرّف طلب آمناً للدعم. اتخذ القرار من حالة HTTP وerror.code الثابت، لا من نص الرسالة المترجم.

{
  "error": {
    "code": "student_not_found",
    "message": "Student not found",
    "request_id": "req_example",
    "details": null
  }
}

لا تستخدم 404 لاستنتاج انتماء معرّف إلى مدرسة أخرى.

تتضمن الاستجابات بعد تقييم الحصة:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset

إعادة الضبط عند منتصف الليل التالي UTC كوقت Unix. وتعني -1 للحد والمتبقي غير محدود، مع إمكان استمرار قياس الاستخدام. تتضمن 429 ترويسة Retry-After. الافتراض الحالي لـEnterprise هو 10,000 طلب في يوم UTC ما لم ينطبق استثناء فعلي.

• لا تكرر 400 أو401 أو403 أو404 أو413 أو415 أو422.
• عند 409 idempotency_request_in_progress انتظر Retry-After وأعد الطلب والقيمة المطابقين.
• عند 429 أو503 استخدم تراجعاً أسياً محدوداً مع عشوائية واحترم Retry-After.
• لا تُعد كتابة غير محسومة إلا بقيمة منع التكرار الأصلية والطلب المطابق.
• ضع حداً للمحاولات وأظهر مهمة فاشلة دائمة لمراجعة المشغّل.

أرسل الوقت وقالب نقطة النهاية وحالة HTTP ورمز الخطأ الثابت وrequest_id. لا ترسل بيانات Bearer أو ترويسة التفويض أو قيمة منع التكرار الخام أو جسم الطلب الكامل أو استجابة بيانات شخصية.

راجع الكتابات المانعة للتكرار و معالجة مشكلات API.