> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

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

> كل أخطاء Didit API: رموز حالة HTTP، وبنية أجسام الاستجابات، ورموز الخطأ الثابتة، والأخطاء التي يمكن إعادة محاولتها بأمان. تشمل 401 و403 و409 و429 و5xx.

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

## رموز الحالة

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

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

لا تشترك أجسام الأخطاء في بنية واحدة، لذا اقرأها بحذر. يختلف الشكل حسب عائلة الـ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 على الإطلاق، لذا عالج الجسم الذي لا يمكن تحليله.

```javascript theme={null}
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](https://docs.didit.me/ar/getting-started/api-authentication.md) و[مفاتيح API](https://docs.didit.me/ar/console/api-keys.md) لمعرفة كيفية عمل المفاتيح وحدودها.

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

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

| الاستدعاء | الحالة | الجسم |
| - | - | - |
| `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"` طالما أن الخدمات المدفوعة متوقفة لمؤسستك.
لا تُحتسب الرسوم على [تطبيقات البيئة التجريبية](https://docs.didit.me/ar/integration/sandbox-testing.md) أبداً، لذا تتخطى هذه الفحوص.

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

قيم `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` قبل أن تنشئ جلسة أخرى.

## ذات صلة

* [تحديد المعدل](https://docs.didit.me/ar/integration/rate-limiting.md): الحدود والرؤوس وجسم استجابة `429`.
* [مصادقة API](https://docs.didit.me/ar/getting-started/api-authentication.md): كيفية إرسال مفتاحك.
* [اختبار البيئة التجريبية](https://docs.didit.me/ar/integration/sandbox-testing.md): أعد إنتاج النتائج دون بيانات حقيقية أو فوترة.
* [Webhooks](https://docs.didit.me/ar/integration/webhooks.md): التسليم وإعادة المحاولات والترتيب.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.