رموز الخطأ
هذه الصفحة هي المرجع الأساسي لمعالجة الأخطاء. رموز الأخطاء الخاصة بكل SDK موثقة في صفحة معالجة الأخطاء لكل SDK؛ وتغطي هذه الصفحة الأخطاء على مستوى عقد API.
رموز حالة HTTP
| الرمز | المعنى | أين يُطبَّق |
|---|---|---|
200 OK | نجح الطلب. | جميع العقود. |
201 Created | تم إنشاء المورد (نادر؛ معظم عمليات الإنشاء تُعيد 200). | عقد API. |
400 Bad Request | الحمولة مشوهة أو الحقول المطلوبة مفقودة. يُحدد النص المشكلة الحقول الإشكالية. | جميع العقود. |
401 Unauthorized | المصادقة مفقودة أو منتهية الصلاحية أو غير صالحة. | جميع العقود. |
403 Forbidden | المصادقة صالحة لكن المستأجر غير مُمكَّن للمورد المطلوب (مثلًا، استدعاء قدرة غير موجودة في APIKEY الخاص بك). | Web & SDK، API. |
404 Not Found | المورد غير موجود أو لا ينتمي إلى المستأجر المصادَق عليه. | جميع العقود. |
409 Conflict | المورد موجود لكنه ليس في الحالة الصحيحة لهذه العملية (مثلًا، جلب مستندات من عملية لا تزال قيد التقدم). | Web & SDK، API. |
410 Gone | المورد كان موجودًا لكن تم حذفه وفق سياسة الاحتفاظ (نقاط نهاية جلب المستندات)، أو العملية موجودة لكنها انتهت في حالة خطأ — انظر الحصول على العملية. | نقاط نهاية جلب المستندات؛ API Get Process. |
429 Too Many Requests | تجاوزت حد المعدل. أعد المحاولة بتراجع أسي. | جميع العقود. |
5xx | خطأ في المنصة. أعد المحاولة بتراجع؛ وإذا استمرت المشكلة، تواصل مع الدعم مع نص الاستجابة والطابع الزمني. | جميع العقود. |
أخطاء المصادقة (401)
| السبب | العَرَض |
|---|---|
| مفتاح خاص خاطئ (التأكيد موقَّع بمفتاح خاطئ) | 401، Authentication failed (1.2.21) |
aud لا يتطابق مع عنوان URL للبيئة | 401 |
حقل exp في الماضي | 401، Authentication failed |
خوارزمية غير مدعومة (استخدم RS256) | 401 |
| خلط بيانات اعتماد sandbox / الإنتاج | 401، حتى لو بدت بيانات الاعتماد صحيحة |
ترويسة APIKEY مفقودة (عقد API فقط) | 401 |
x-api-key غير صالح (Magic Link فقط) | 401 |
راجع المصادقة > الأخطاء الشائعة للاطلاع على قائمة استكشاف الأخطاء الكاملة.
نتائج على مستوى القدرة (200 مع نتيجة سلبية)
200 OK لا يعني أن المستخدم اجتاز التحقق — بل يعني أن المنصة أكملت العمل. القرار المتعلق بالمستخدم يكمن في نص الاستجابة، وليس في حالة HTTP:
| الحقل | القيمة السلبية | أين يظهر |
|---|---|---|
process.result | PROCESS_RESULT_FAILED | Web & SDK |
process.authenticationInfo.livenessResult | NO | Web & SDK |
liveness | 2 | API |
unicoId.result | no | API |
data.result.status | not_verified | Magic Link |
سياسة إعادة المحاولة
| الحالة | هل تُعاد المحاولة؟ | الطريقة |
|---|---|---|
5xx | نعم | تراجع أسي (1 ثانية، 2 ثانية، 4 ثوانٍ، 8 ثوانٍ، …). حد أقصى 5 محاولات. |
429 | نعم | احترم ترويسة Retry-After إن وُجدت؛ وإلا استخدم التراجع الأسي. |
4xx (أخرى) | لا | الطلب خاطئ. صحح المدخلات قبل إعادة المحاولة. |
401 | مشروط | جدد رمز الوصول مرة واحدة. إذا أعاد الطلب الجديد 401 أيضًا، فالمشكلة هيكلية — لا تعد المحاولة. |
لا تُوفر منصة IDCloud حاليًا آلية مفتاح أمانة (idempotency-key) على نقاط نهاية الإنشاء. توخَّ الحذر عند إعادة محاولة POST /client/v1/process أو POST /processes/v1 — قد يكون خطأ الشبكة على 5xx قد نجح فعليًا من جهة الخادم، وقد تُنشئ إعادة المحاولة عملية مكررة. عند الشك، استرجع العمليات الأخيرة بمعرف الارتباط الداخلي قبل إعادة المحاولة.
أين توجد أخطاء SDK
كتالوجات الأخطاء الخاصة بـ Web SDK و Android SDK و iOS SDK و Flutter SDK موثقة في صفحة معالجة الأخطاء المخصصة لكل SDK:
- Web SDK > معالجة الأخطاء
- Android SDK > معالجة الأخطاء
- iOS SDK > معالجة الأخطاء
- Flutter SDK > معالجة الأخطاء
تغطي هذه الصفحات أخطاء جانب الجهاز (رفض إذن الكاميرا، انتهاء مهلة الالتقاط، الشبكة غير متوفرة على الجهاز) — بشكل منفصل عن أخطاء جانب API الموثقة هنا.