---
title: "الأخطاء"
url: https://docs.growamal.com/ar/errors/
language: ar
---

# الأخطاء

## مغلَّف الخطأ

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

```json
{
  "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`. انظر [المفاهيم الأساسية ← العزل المستأجِر](https://docs.growamal.com/ar/core-concepts/).

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

رموز الأخطاء الرئيسية التي يجب على مستهلِك الواجهة التعامل معها مسرودة أدناه. للاطلاع على الرموز الدقيقة التي قد تعيدها نقطة نهاية بعينها، اقرأ `responses` تلك العملية في [مرجع الواجهة البرمجية](https://docs.growamal.com/ar/api-reference/).

| `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` | حالة المهارة، الملف، المراقبة | الأدلة منقسمة أو غير كافية؛ على كل مستهلِك لاحق التوقّف والانتظار. انظر [محرك القرار](https://docs.growamal.com/ar/how-it-works/decision-engine/). |
| `blocked_insufficient_evidence` | توصية الحزمة | لا يمكن توصية حزمة بعد؛ وتذكر الاستجابة إجراء البيانات التالي. |
| `no_eligible_item` | تسليم المهام | لا عنصر مخزَّن يطابق الطلب؛ يُبلَّغ عنه بـ `200` مع `served: null` (إعلان صريح، لا استبدال صامت). |
| `DATA_INCOMPLETE` (`PR2-00`) | حلّ الملف | ملف حارس نظامي لا ملف تربوي حقيقي، يُستبعَد الطالب من التجميع والتفعيل الجماعي. |

تستخدم أعلام السياق قاموسًا مغلقًا: اختيار علم محظور (أو أي ملاحظة نصّية حرّة عن طالب) مرفوض، **لا يوجد
مسار نصّي حرّ** على سجلّ الطالب (V-12). انظر [سلامة اللغة](https://docs.growamal.com/ar/guides/language-safety/).

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

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