أخطاء Didit API: رموز الحالة والاستجابات والحلول

يُبلغ Didit API عن الفشل برمز حالة HTTP، وفي كل حالة تقريباً بجسم JSON. تسرد هذه الصفحة معنى كل حالة، وشكل الجسم، وقيم code التي يمكنك الاعتماد عليها في التفرع، والإخفاقات التي يمكن إعادة محاولتها بأمان. اعتمد على الحالة أولاً، وعلى code عند وجوده، لأن نص الرسالة قد يتغير.

رموز الحالة

الحالة	المعنى	الإجراء	إعادة المحاولة؟
`400`	الطلب غير صالح: فشل التحقق من صحة حقل، أو تعذّرت قراءة صورة أو مستند	صحِّح ما يذكره الجسم	بعد التصحيح
`401`	المفتاح الذي أرسلته خاطئ أو بتنسيق غير صحيح أو ملغى أو منتهي الصلاحية	تحقق من `DIDIT_API_KEY`، أو أنشئ مفتاحاً جديداً	بعد التصحيح
`402`	تعذّر دفع ثمن الفحص، لذا لم يُنفَّذ	اشحن رصيدك	بعد شحن الرصيد
`403`	لم يُرسل أي مفتاح، أو المفتاح لا يملك صلاحية الوصول إلى هذا المورد أو هذا الإجراء، أو جاء الطلب من خارج قائمة عناوين IP الخاصة بالمفتاح، أو الرصيد لا يغطي الاستدعاء	اقرأ الجسم، ثم راجع أخطاء مفتاح API والرصيد غير كافٍ	بعد التصحيح
`404`	المورد غير موجود، أو الجلسة خارج سير العمل أو الحالات المسموح بها للمفتاح	تحقق من المعرّف وحدود المفتاح	لا
`409`	الطلب يتعارض مع الحالة الحالية، مثل إعادة استخدام `Idempotency-Key` أو خطوة سبق تنفيذها	اقرأ `code` وأعد تحميل الحالة	يعتمد على `code`
`410`	انتهت صلاحية المورد، مثل جلسة أو دعوة	أنشئ واحداً جديداً	لا
`415`	جسم الطلب ليس بصيغة JSON	أرسل `Content-Type: application/json`	بعد التصحيح
`422`	عنوان المحفظة ينطبق على أكثر من بلوكتشين، لذا لم يُفحص ولم تُحتسب عليه أي رسوم	أعد الإرسال مع ضبط `blockchain` على إحدى قيم `candidate_chains`	بعد التصحيح
`429`	تم بلوغ حد المعدل أو حصة	انتظر `Retry-After`؛ راجع حد المعدل	نعم، بعد الانتظار
`500`	خطأ غير متوقع من جهة Didit	أعد المحاولة مع تراجع تدريجي، وتواصل مع الدعم إن استمر	راجع إعادة المحاولة
`502`	أعادت خدمة تعتمد عليها Didit خطأً	اقرأ `code`	راجع إعادة المحاولة
`503`	خدمة تعتمد عليها Didit غير متاحة مؤقتاً	اقرأ `code` وأعد المحاولة لاحقاً	راجع إعادة المحاولة

أجسام الأخطاء

لا تشترك أجسام الأخطاء في بنية واحدة، لذا اقرأها بحذر. يختلف الشكل حسب عائلة الـendpoint:

الشكل	أين تراه	مثال
`detail`	معظم الأخطاء، بما فيها المصادقة وعدم العثور على المورد وحدود المعدل	`{"detail": "You do not have permission to perform this action."}`
`detail` و`code`	الأخطاء التي تحمل رمزاً ثابتاً	`{"detail": "This application was deleted.", "code": "application_deleted"}`
أخطاء الحقول	التحقق من صحة المدخلات	`{"workflow_id": ["This field is required."]}`
`non_field_errors`	التحقق من صحة عدة حقول معاً	`{"non_field_errors": ["..."]}`
مصفوفة JSON	بعض أخطاء التحقق، مثل استدعاء المحاكاة	`["Scenario can only be armed before the verification starts."]`
`error`	معظم الواجهات البرمجية المستقلة	`{"error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}`
`error` و`code`	أخطاء الصور في الواجهات البرمجية المستقلة	`{"error": "...", "code": "invalid_image"}`
`error` كرمز، مع `detail`	التحقق من محفظة الهوية الرقمية	`{"error": "insufficient_credits", "detail": "..."}`

قد لا يحمل 500 أي جسم JSON على الإطلاق، لذا عالج الجسم الذي لا يمكن تحليله.

const raw = await response.text();
let body = {};
try {
  body = JSON.parse(raw);
} catch {
  // A 5xx response may not be JSON: rely on response.status.
}
const code = body.code ?? null;
const message = body.detail ?? body.error ?? (Array.isArray(body) ? body[0] : raw);

أخطاء مفتاح API

ما أرسلته	الحالة	`detail`
لا توجد ترويسة `x-api-key`	`403`	`You do not have permission to perform this action.`
مفتاح خاطئ أو بتنسيق غير صحيح أو ملغى	`401`	`Authentication credentials were not provided or are invalid.`
مفتاح منتهي الصلاحية	`401`	`This API key has expired.`
مفتاح استُخدم من خارج قائمة عناوين IP الخاصة به	`403`	`This API key can't be used from this IP address.`
مفتاح محدود النطاق دون صلاحية الوصول إلى هذا المورد أو هذا الإجراء	`403`	`This API key has no access to this endpoint.`
مفتاح محدود ببعض سير العمل أو الحالات، على endpoint لا يستطيع استخدامه	`403`	`This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint.`
مفتاح محدود ببعض سير العمل أو الحالات، على جلسة خارج هذه الحدود	`404`	`Session not found.`
مفتاح يخص تطبيقاً حُذف للتو	`403`	`This application was deleted.`، مع `"code": "application_deleted"`

لبضع دقائق بعد حذف التطبيق تُجيب الواجهة بالرمز application_deleted، وبعد ذلك ترفض المفتاح كأي مفتاح خاطئ. لا تُعِد المحاولة: التطبيق ومفاتيحه لم تعد موجودة. راجع مصادقة API ومفاتيح API لمعرفة كيفية عمل المفاتيح وحدودها.

الرصيد غير كافٍ

تُبلغ كل عائلة واجهات عن الرصيد المنخفض بطريقتها الخاصة:

الاستدعاء	الحالة	الجسم
`POST /v3/session/`	`400`	`{"detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}`
معظم الواجهات المستقلة	`403`	`{"error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}`
`POST /v3/bank/account-check/`	`402`	`{"detail": "...", "code": "insufficient_credits"}`
التحقق من محفظة الهوية الرقمية	`403`	`{"error": "insufficient_credits", "detail": "..."}`
المعاملات وTravel Rule والتحقق من العناوين	`403`	`{"detail": "...", "code": "insufficient_credits"}`

في حالة وجود عقد، يُجيب إنشاء الجلسة بالحالة 403 مع "code": "contract_billing_suspended" طالما أن الخدمات المدفوعة متوقفة لمؤسستك. لا تُحتسب الرسوم على تطبيقات البيئة التجريبية أبداً، لذا تتخطى هذه الفحوص.

رموز الأخطاء

قيم code هذه ثابتة، لذلك يمكنك بناء منطق التفرع عليها. تظهر معظمها بجانب detail؛ وفي التحقق من محفظة الهوية الرقمية، تكون القيمة هي قيمة error.

الوصول والفوترة

الرمز	الحالة	المعنى
`insufficient_credits`	`402`, `403`	الرصيد لا يكفي لتغطية الاستدعاء
`contract_billing_suspended`	`403`	الخدمات المدفوعة متوقفة مؤقتاً لهذه المؤسسة
`contract_rate_missing`	`402`, `403`	لا يتضمن العقد سعراً لهذا الفحص
`application_deleted`	`403`	حُذف التطبيق الخاص بالمفتاح
`organization_deleted`	`403`	حُذفت المؤسسة الخاصة بالمفتاح
`event_monitoring_disabled`	`403`	إدخال الأحداث غير مفعّل لهذا التطبيق
`networks_not_entitled`	`403`	شبكات الاحتيال غير مفعّلة لهذه المؤسسة

الطلبات وidempotency

الرمز	الحالة	المعنى
`invalid_image`	`400`	تعذر استخدام الصورة
`return_url_invalid`	`400`	عنوان URL للعودة غير مسموح به
`idempotency_key_invalid`	`400`	يتجاوز `Idempotency-Key` 255 حرفاً
`idempotency_key_reused`	`409`	سبق استخدام المفتاح مع محتوى طلب مختلف
`idempotency_key_in_progress`	`409`	الطلب الأول بهذا المفتاح ما زال قيد التنفيذ؛ انتظر `Retry-After`
`verification_in_progress`	`409`	المستخدم يُكمل هذا التحقق الآن، لذلك لا يمكن إلغاؤه؛ انتظر `Retry-After`
`feature_override_not_pending`	`409`	طُبّق التجاوز مسبقاً أو أُلغي

فحوصات البنوك والهاتف والمخاطر

الرمز	الحالة	المعنى
`invalid_account_input`	`400`	بيانات الحساب غير صالحة
`country_not_covered`	`404`	لا يغطي الفحص هذه الدولة أو هذا النوع من الحسابات
`bank_not_covered`	`404`	لا يصل الفحص إلى هذا البنك
`bank_verification_not_available`	`404`	التحقق المصرفي غير متاح
`account_check_unavailable`	`503`	الفحص غير متاح مؤقتاً ولم تُحتسب رسوم على الطلب
`phone_provider_unavailable`	`502`	التحقق من رقم الهاتف غير متاح مؤقتاً؛ لا تُحتسب أي رسوم ولا تُستهلك أي محاولة
`risk_lookup_unavailable`	`502`	الاستعلام عن المخاطر غير متاح مؤقتاً ولم تُحتسب رسوم على الطلب

التحقق من الشركات (KYB)

الرمز	الحالة	المعنى
`kyb_registry_provider_unavailable`	`502`	سجل الشركات غير متاح مؤقتاً
`kyb_registry_country_unsupported`	`400`	البحث في السجل لا يغطي هذه الدولة
`kyb_registry_search_limit_reached`	`429`	وصل التطبيق إلى حده البالغ 600 عملية بحث مدفوعة في الساعة
`kyb_session_not_writable`	`409`	الجلسة منتهية
`kyb_step_mismatch`	`409`	الجلسة في خطوة أخرى؛ يحدد `next_step` هذه الخطوة
`kyb_no_party_drafts`	`409`	لا توجد مسودات أطراف لإرسالها
`kyb_parties_already_submitted`	`409`	أُرسلت الأطراف من قبل
`kyb_party_kyc_session_not_deleted`	`409`	التحقق الخاص بالطرف ما زال نشطاً، لذلك لا يمكن إعادة إنشائه

محافظ الهوية الرقمية

الرمز	الحالة	المعنى
`wallet_unavailable`	`403`	هذه المحفظة غير متاحة لتطبيقك
`wallet_provider_unavailable`	`502`	تعذر بدء المحفظة، ولم يُنشأ أي شيء
`wallet_not_configured`	`503`	لا يمكن لهذه البيئة الوصول إلى المحفظة

التقارير والحالات

الرمز	الحالة	المعنى
`report_deletion_pending`	`409`	التقرير قيد الحذف؛ كرر عملية الحذف لإتمام محو ملفاته
`report_storage_unavailable`	`503`	تعذر محو ملفات التقرير؛ كرر عملية الحذف
`wallet_address_deletion_incomplete`	`503`	تعذر حذف ملف مخزَّن، فتوقف الحذف؛ حاول مرة أخرى
`case_request_not_waiting`	`409`	الطلب لم يعد بانتظار العميل، لذلك لا يوجد شيء لتذكير العميل به
`case_request_reminder_too_soon`	`429`	أُرسل تذكير مؤخراً؛ يحدد `retry_at` الموعد الذي يمكنك فيه إرسال التذكير التالي

التوقيع الإلكتروني

الرمز	الحالة	المعنى
`signature_not_found`	`404`	التوقيع غير موجود
`signature_field_not_found`	`404`	حقل التوقيع غير موجود
`signature_not_signed`	`404`, `409`	لم يُوقَّع المستند

عند إنشاء جلسة، تظهر مشكلات المستند أدناه كقيمة للحقل المعني مع الحالة 400، على سبيل المثال: {"sign": "signature_document_changed"}:

القيمة	المعنى
`signature_document_changed`	المستند يختلف عن المستند المُرسل أولاً
`signature_document_not_supported`	صيغة المستند غير مدعومة
`signature_document_conversion_failed`	تعذر تحويل المستند
`field_anchor_not_found`	لم يُعثر على مرساة النص الخاصة بالحقل في المستند
`field_value_missing`	لا توجد قيمة للحقل

webhook

الرمز	الحالة	المعنى
`webhook_url_missing`	`400`	لا يوجد عنوان URL مسجل لهذا التسليم، لذلك لا يُرسل شيء
`invalid_webhook_payload`	`400`	بيانات webhook ليست بصيغة صالحة
`webhook_resend_error`	`400`	تعذر توقيع التسليم المخزَّن مرة أخرى، أو تعذر إكمال المحاولة

إعادة المحاولة وidempotency

بعض الأخطاء يمكن تكرار الطلب بعدها بأمان، وبعضها لا يمكن:

429: انتظر القيمة الموجودة في الرأس Retry-After، ثم أعد المحاولة.
502 و503: أعد المحاولة مع التراجع التدريجي (backoff) عندما ينص مرجع endpoint على أنه لم يُحتسب أي رسوم، كما هو الحال في فحوصات الهاتف والبريد الإلكتروني والمصرفية وفحوصات المخاطر.
502 على POST /v3/database-validation/: اقرأ كل عنصر في validation_errors أولاً، لأن هذه الحالة وحدها لا تعني فشلاً مؤقتاً.
503 عند الحذف: كرر الطلب نفسه حتى يُرجع 200.
4xx الأخرى: أصلح الطلب أولاً، لأن الطلب نفسه سيفشل بالطريقة نفسها.

تقبل POST /v3/aml/ والتحقق من محفظة الهوية الرقمية الرأس Idempotency-Key بطول يصل إلى 255 حرفاً. تكرار الطلب بالمفتاح نفسه والمحتوى نفسه يعيد الاستجابة المخزنة، فتُنفَّذ العملية وتُحتسب الرسوم مرة واحدة فقط. المفتاح نفسه مع محتوى مختلف يُرجع 409، وأثناء تشغيل الطلب الأول تُرجع endpoints المحفظة 409 مع Retry-After. لا تملك POST /v3/session/ مفتاح idempotency، لذلك إذا انتهت مهلة إنشاء جلسة، فاستعرض جلساتك باستخدام vendor_data قبل أن تنشئ جلسة أخرى.

الأدلة

المصادقة

Model Context Protocol (MCP)

SDKs الويب

SDKs الأصلية

SDKs الخادم

التكاملات

أخطاء Didit API: رموز الحالة والاستجابات والحلول

رموز الحالة

أجسام الأخطاء

أخطاء مفتاح API

الرصيد غير كافٍ

رموز الأخطاء

الوصول والفوترة

الطلبات وidempotency

فحوصات البنوك والهاتف والمخاطر

التحقق من الشركات (KYB)

محافظ الهوية الرقمية

التقارير والحالات

التوقيع الإلكتروني

webhook

إعادة المحاولة وidempotency

ذات صلة

​رموز الحالة

​أجسام الأخطاء

​أخطاء مفتاح API

​الرصيد غير كافٍ

​رموز الأخطاء

​الوصول والفوترة

​الطلبات وidempotency

​فحوصات البنوك والهاتف والمخاطر

​التحقق من الشركات (KYB)

​محافظ الهوية الرقمية

​التقارير والحالات

​التوقيع الإلكتروني

​webhook

​إعادة المحاولة وidempotency

​ذات صلة

رموز الحالة

أجسام الأخطاء

أخطاء مفتاح API

الرصيد غير كافٍ

رموز الأخطاء

الوصول والفوترة

الطلبات وidempotency

فحوصات البنوك والهاتف والمخاطر

التحقق من الشركات (KYB)

محافظ الهوية الرقمية

التقارير والحالات

التوقيع الإلكتروني

webhook

إعادة المحاولة وidempotency

ذات صلة