الأخطاء

مغلَّف الخطأ

كل خطأ، عند أي حالة، يستخدم شكلًا واحدًا: مخطّط ApiError:


{
  "code": "VALIDATION_ERROR",
  "message": "Human-readable description.",
  "details": [{ "field": "password", "issue": "too short" }],
  "retryAfter": 60
}

code: مفتاح ثابت يقرؤه الجهاز (موجود دائمًا).
message: نصّ مقروء للبشر (موجود دائمًا).
details[]: مشكلات التحقّق لكل حقل ({ field, issue })، تظهر عند فشل التحقّق.
retryAfter: ثواني الانتظار، تظهر في الاستجابات المحدودة بالمعدّل.

حالات HTTP

الحالة	متى
`401`	غير مُصادَق · بيانات اعتماد خاطئة · رمز وصول منتهٍ · رمز تجديد غير صالح/مُدوَّر · رمز سريع غير صالح/منتهٍ · إقفال القوة الغاشمة للدخول (مع `Retry-After`)
`403`	مُصادَق لكن دون صلاحية داخل مؤسستك (مثل تسجيل ثانٍ، أو نطاق خاطئ)
`404`	غير موجود أو عبر مؤسسة (خصوصية: لا يؤكّد أبدًا وجود مورد أجنبي)
`409`	تعارض: صفّ به طلاب عند الحذف · معلّم مُسنَد سلفًا · تصادم رمز سريع
`422`	تحقّق: `school.country` ≠ `org.country` · صفّ خارج 1-4 · slug خاطئ · كلمة مرور قصيرة

القوة الغاشمة للدخول تعيد 401 + Retry-After، لا 429. لا تصدر هذه الواجهة 429 صريحًا لحدّ الدخول. اقرأ ترويسة Retry-After (وretryAfter في الجسم) وتراجع.

404 ≠ «غير موجود». مورد حقيقي في مؤسسة أخرى يُبلَّغ عنه بـ 404 بحسب التصميم. ومورد في مؤسستك لا يصله دورك يكون 403. انظر المفاهيم الأساسية ← العزل المستأجِر.

دليل رموز الأخطاء

رموز الأخطاء الرئيسية التي يجب على مستهلِك الواجهة التعامل معها مسرودة أدناه. للاطلاع على الرموز الدقيقة التي قد تعيدها نقطة نهاية بعينها، اقرأ responses تلك العملية في مرجع الواجهة البرمجية.

`code`	حالة HTTP	متى يُطلَق
`INVALID_CREDENTIALS`	`401`	بيانات اعتماد خاطئة عند تسجيل الدخول
`TOKEN_MISSING`	`401`	لا ترويسة `Authorization` على مسار محمي
`TOKEN_INVALID`	`401`	رمز وصول مشوَّه أو غير معترَف به
`TOKEN_EXPIRED`	`401`	انتهت صلاحية رمز الوصول (15 دقيقة)؛ استدعِ `POST /api/auth/refresh`
`SESSION_REVOKED`	`401`	رمز التجديد دُوِّر أو أُلغي صراحةً
`BRUTE_FORCE_LOCKED`	`401`	محاولات دخول فاشلة كثيرة؛ احترم ترويسة `Retry-After` قبل إعادة المحاولة
`QUICKCODE_INVALID_OR_EXPIRED`	`401`	الرمز السريع للطالب أو رمز الصف غير صالح أو غير معروف أو منتهٍ (إجابة واحدة للجميع فلا يمكن التخمين)
`CLASS_CODE_EXPIRED`	`410`	في `GET /api/auth/student/class-preview` فقط: رابط دخول الصف جُدِّد أو انتهت مدّته؛ اطلب الرابط الجديد من المعلّم
`QUICKCODE_RATE_LIMIT`	`401`	محاولات رمز سريع كثيرة جدًا من المصدر نفسه
`PERMISSION_DENIED`	`403`	مُصادَق لكن مجموعة صلاحيات المستدعي لا تغطّي العملية
`CONTEXT_FLAG_BLOCKED`	`403`	علم السياق المختار في قائمة المحظورات؛ لا يوجد مسار ملاحظة نصّية حرّة
`NOT_FOUND`	`404`	المورد غير موجود في هذه المؤسسة (يُستخدَم أيضًا عبر المؤسسات لتجنّب كشف المعرّفات الأجنبية)
`EMAIL_EXISTS`	`409`	محاولة إنشاء مستخدم ببريد إلكتروني موجود مسبقًا
`CONFLICT`	`409`	تعارض عام: صفّ به طلاب عند الحذف، تصادم رمز سريع، أو تعارض حالة آخر
`DO_NOT_DECIDE_YET`	`200`	توقّف آمن لمحرّك القرار: الأدلة منقسمة أو غير كافية؛ انظر جدول التوقّف الآمن أدناه
`VALIDATION_ERROR`	`422`	فشل التحقّق من جسم الطلب؛ `details[]` يُسمّي كل حقل فاشل
`RATE_LIMITED`	`429`	تجاوُز حدّ المعدّل العام (مثل `POST /api/logs/client`)؛ احترم `Retry-After`
`ENGINE_UNAVAILABLE`	`503`	تعذّر الوصول إلى محرّك التشخيص أو التصنيف
`STATE_EXPIRED`	`401`	حالة OAuth أو رمز تسليم أحادي الاستخدام انتهت صلاحيته أو استُهلك مسبقًا
`INTERNAL`	`500`	خطأ غير متوقّع في الخادم

استجابات «التوقّف الآمن» لمحرّك القرار (ليست أخطاء)

تُعيد عدّة نقاط نهاية في محرّك الاستجابة للتدخّل الحالة 200 مع نتيجة غير حاسمة بدلًا من خطأ حين لا تكفي البيانات لاتخاذ قرار. هذه توقّفات سلامة مقصودة (V-3)، لا إخفاقات. اقرأ حقل النتيجة واعرض حالة «بحاجة إلى مزيد من البيانات» بدل إعادة المحاولة:

النتيجة	أين	المعنى
`do_not_decide_yet`	حالة المهارة، الملف، المراقبة	الأدلة منقسمة أو غير كافية؛ على كل مستهلِك لاحق التوقّف والانتظار. انظر محرك القرار.
`blocked_insufficient_evidence`	توصية الحزمة	لا يمكن توصية حزمة بعد؛ وتذكر الاستجابة إجراء البيانات التالي.
`no_eligible_item`	تسليم المهام	لا عنصر مخزَّن يطابق الطلب؛ يُبلَّغ عنه بـ `200` مع `served: null` (إعلان صريح، لا استبدال صامت).
`DATA_INCOMPLETE` (`PR2-00`)	حلّ الملف	ملف حارس نظامي لا ملف تربوي حقيقي، يُستبعَد الطالب من التجميع والتفعيل الجماعي.

تستخدم أعلام السياق قاموسًا مغلقًا: اختيار علم محظور (أو أي ملاحظة نصّية حرّة عن طالب) مرفوض، لا يوجد مسار نصّي حرّ على سجلّ الطالب (V-12). انظر سلامة اللغة.

إرشادات إعادة المحاولة

عند استجابة محدودة بالمعدّل، احترم Retry-After قبل إعادة المحاولة.
عند انتهاء رمز الوصول، استدعِ POST /api/auth/refresh؛ لا تُعِد تسجيل الدخول.
تُصفَّر نوافذ حدّ المعدّل عند نجاح طلب.