الأخطاء ورموز الحالة
هذه الصفحة هي المرجع الموحّد لأغلفة الاستجابة التي يستخدمها كل مسار في واجهة API الخاصة بنطاق القروض. يسرد توثيق كل مسار رموز الحالة التي يُصدرها ذلك المسار تحديدًا؛ أما هذه الصفحة فتوثّق شكل كل غلاف وفهرس قيم code المسمّاة التي قد تتلقاها.
اقرأها مرة قبل التكامل؛ وعُد إليها كلما فاجأتك حالة غير 2xx.
فهرس رموز الحالة
| الحالة | متى تراها | مسار مثال |
|---|---|---|
200 OK | قراءة ناجحة، أو إعادة تشغيل متكررة دون أثر، أو إلغاء منطقي، أو معالجة دفعة مجمّعة، أو انتقال في الحالة. | كل المسارات غير المخصّصة للإنشاء. |
201 Created | إنشاء ناجح لأول مرة في مسار سجل واحد. | POST /borrowers. |
202 Accepted | بدأ الاستيراد غير المتزامن — ويستمر العمل في الخلفية. | POST /imports. |
204 No Content | لا يُرجعه حاليًا أي مسار في نطاق القروض. | — |
400 Bad Request | فشل التحقق من الطلب: JSON غير سليم، أو استعلام غير سليم، أو مخالفة للمخطط. | كل مسارات التعديل. |
401 Unauthorized | لا توجد ترويسة Authorization، أو رمز مجهول، أو رمز مُلغى. | كل المسارات. |
403 Forbidden | المستدعي حساب مستثمر؛ ولا يمكن للمستثمرين استخدام واجهة بيانات المراقبة البرمجية (MONITORING_INVESTOR_FORBIDDEN). أما ?unmask=true من غير مسؤول فلا يُرجع 403، بل يُرجع 200 مع إخفاء المعلومات الشخصية. | كل المسارات. |
404 Not Found | المورد غير موجود أو ينتمي إلى مؤسسة أخرى. | كل المسارات التي تشير إلى مورد. |
409 Conflict | يوجد بالفعل صف حي بهذا id، أو أُعيد استخدام Idempotency-Key لانتقال حالة مختلف، أو لم تتمكن مرحلة الالتزام من رؤية الملف المرفوع. | POST /borrowers، PATCH /loans/.../status، POST /imports/{id}/commit. |
413 Payload Too Large | دفعة NDJSON مجمّعة تتجاوز حد الصفوف أو البايتات. | POST /bulk/{entity}. |
422 Unprocessable Entity | الصف المشار إليه غير موجود كصف حي في المحفظة نفسها (REFERENCED_ENTITY_NOT_FOUND)، أو انتقال الحالة المطلوب غير موجود في مصفوفة الانتقالات (INVALID_STATUS_TRANSITION). تستخدم حالات فشل التحقق 400. | POST /loans، POST /payments، PATCH /loans/{loanRef}/status. |
429 Too Many Requests | تجاوز حد المعدّل. تطبّق المنصة حدود معدّل لكل مؤسسة؛ وتشير ترويسة الاستجابة Retry-After إلى عدد الثواني. | كل المسارات. |
500 Internal Server Error | خطأ غير معالَج في المنصة. عامِله كخطأ عابر؛ ومن الآمن إعادة المحاولة بالمفتاح Idempotency-Key نفسه. | كل المسارات. |
عامِل أي 4xx غير 429 على أنه عيب في الطلب — ينبغي لمنطق عميلك رفض المُدخل بدلًا من إعادة المحاولة. وعامِل 429 و500 على أنهما عابران وأعد المحاولة مع تراجع تدريجي؛ إذ يجعل Idempotency-Key إعادة المحاولة آمنة.
الأغلفة القياسية
تستخدم واجهة API الخاصة بنطاق القروض ثلاثة أغلفة استجابة لرموز الحالة غير الناجحة. ويخبرك شكل الغلاف بنوع الفشل الذي تنظر إليه.
غلاف التحقق — 400 Bad Request
يُستخدم لمخالفات المخطط، ومعاملات الاستعلام غير السليمة، والمسارات غير السليمة.
{
"error": "Validation failed",
"fieldErrors": [
{ "path": "interestRateApr", "message": "interestRateApr must be >= 0" },
{ "path": "termMonths", "message": "termMonths must be > 0" }
]
}| الحقل | النوع | ملاحظات |
|---|---|---|
error | string | ملخص قصير مقروء للبشر. |
fieldErrors[].path | string | المسار المنقّط إلى الحقل المخالف. تشير (root) إلى المتن نفسه، مثلًا عند فشل تحليل JSON. |
fieldErrors[].message | string | شرح مقروء للبشر. |
تُصدر بعض المسارات errors[] بدلًا من fieldErrors[] لحالات فشل معاملات الاستعلام (إذ يختلف اصطلاح إطار العمل من واجهة إلى أخرى). شكل path/message متطابق؛ فعامِل اسمَي المصفوفتين على أنهما قابلان للتبادل لأغراض التحليل.
غلاف الرمز المسمّى — 4xx
يُستخدم عندما يكون للفشل سبب محدد تسمّيه المنصة بقيمة code ثابتة. وجود fieldErrors اختياري ويعتمد على ما إذا كان يمكن نسب الفشل إلى حقل محدد.
{
"error": "a borrower with this id already exists",
"code": "ID_CONFLICT",
"fieldErrors": [
{ "path": "id", "message": "a borrower with this id already exists" }
]
}| الحقل | النوع | ملاحظات |
|---|---|---|
error | string | ملخص مقروء للبشر. |
code | string | رمز ثابت مقروء آليًا؛ راجع المسرد. |
fieldErrors[] | array | غائب | يظهر عندما يشير الفشل إلى حقل محدد. |
تحمل بعض الأغلفة سياقًا منظَّمًا إضافيًا — فمثلًا يتضمن batch_too_large كتلة fieldErrors تسمّي الحد الذي جرى تجاوزه. ويسمّي توثيق كل مسار هذه الحالات.
غلاف الخطأ المجرّد — 404 / 401
يُستخدم للاستجابات المقتضبة حيث لن يساعد أي سياق إضافي المستدعي. و404 هو المثال المعتاد:
{ "error": "Not found" }تُرجع بعض المسارات { "error": "...", "code": "NOT_FOUND" }؛ فعامِل وجود code أو غيابه في 404 على أنه معلوماتي، لا أساسي.
فضاءا رموز: أحرف كبيرة مقابل أحرف صغيرة
تستخدم واجهة API الخاصة بنطاق القروض فضاءَي أسماء متمايزين لقيم code، يفصل بينهما شكل الاستيعاب عن قصد:
- مسارات السجل الواحد (طلبات POST وPATCH، والإلغاء، وطلبات GET الخاصة بالمطابقة) تُصدر قيم رموز
UPPER_CASE:ID_CONFLICT،PORTFOLIO_NOT_FOUND،REFERENCED_ENTITY_NOT_FOUND،INVALID_STATUS_TRANSITION،CHECK_VIOLATION،NOT_FOUND،UNKNOWN_KIND،COMMIT_FAILED،IDEMPOTENCY_CONFLICT،IDEMPOTENCY_KEY_REUSED،MONITORING_INVESTOR_FORBIDDEN. تُرجع مسارات NDJSON المجمّع أيضًاMONITORING_INVESTOR_FORBIDDENبالأحرف الكبيرة. - مسارات NDJSON المجمّع تُصدر قيم رموز
lower_case:batch_too_large،portfolio_not_found،portfolio_id_required،invalid_body،invalid_json، إضافةً إلى الرموز لكل صف الموثّقة أدناه.
عندما تتفرّع في عميلك بناءً على code، طابِق حالة الأحرف بدقة. كل فضاء من فضاءَي الرموز ثابت بشكل مستقل؛ فلا توحّدهما.
مسرد رموز الأخطاء
ترفق المنصة code ثابتًا بكل نمط فشل مسمّى. استخدم هذه الرموز للتفرّع البرمجي؛ فنص رسالة error قد يتطور.
فضاء رموز السجل الواحد
| الرمز | الحالة | يُصدره | المُسبِّب |
|---|---|---|---|
ID_CONFLICT | 409 | POST /borrowers، POST /loans، POST /payments. | يوجد بالفعل صف حي بالقيمة نفسها لـ id. |
PORTFOLIO_NOT_FOUND | 404 | كل مسارات الكتابة للسجل الواحد. | portfolioId الوارد في المتن غير موجود في مؤسستك. |
REFERENCED_ENTITY_NOT_FOUND | 422 | POST /loans، POST /payments. | يشير borrowerId أو loanId إلى صف غير موجود كصف حي في المحفظة نفسها. |
INVALID_STATUS_TRANSITION | 422 | PATCH /loans/{loanRef}/status. | زوج حالتَي المصدر/الوجهة غير موجود في مصفوفة الانتقالات. |
IDEMPOTENCY_CONFLICT | 409 | PATCH /loans/{loanRef}/status. | سبق استخدام Idempotency-Key لانتقال حالة مختلف. أرسل الانتقال الجديد بمفتاح جديد. |
IDEMPOTENCY_KEY_REUSED | 409 | POST /imports. | سبق استخدام Idempotency-Key لاستيراد بمعاملات طلب مختلفة (kind، filename، sizeBytes، …). تتضمن الاستجابة importId وmismatchedFields. أرسل الاستيراد الجديد بمفتاح جديد. |
MONITORING_INVESTOR_FORBIDDEN | 403 | جميع مسارات القروض في المراقبة، بما فيها مسارات NDJSON المجمّع. | المستدعي حساب مستثمر؛ ولا يمكن للمستثمرين استخدام واجهة بيانات المراقبة البرمجية. |
CHECK_VIOLATION | 400 | POST /payments. | فشلت قاعدة بيانات (عادةً ثابت الإعفاء؛ إذ ترفض طبقة المخطط الشكل نفسه وقت التحقق). |
NOT_FOUND | 404 | GET /borrowers/{id}، GET /payments/{id}، PATCH /loans/.../status، POST /payments/{id}/cancel، GET /loans/{externalId}. | الصف المطلوب غير موجود كصف حي في النطاق المقدَّم، أو ينتمي إلى مؤسسة أخرى. |
UNKNOWN_KIND | 400 | POST /imports. | kind ليس واحدًا من أنواع القروض الستة. تتضمن الاستجابة مصفوفة allowed. |
COMMIT_FAILED | 409 | POST /imports/{id}/commit. | لم تتمكن المنصة من العثور على الملف المرفوع؛ وعادةً لم يكتمل الرفع. أعِد الرفع، ثم أعِد الالتزام. |
فضاء رموز NDJSON المجمّع
| الرمز | الحالة | المُسبِّب |
|---|---|---|
batch_too_large | 413 | يتجاوز المتن 10 000 صف أو 10 MB. يميّز error وfieldErrors[].message بين حد الصفوف وحد البايتات. |
portfolio_id_required | 400 | ?portfolioId=<UUID> مفقود أو ليس UUID صالحًا. |
portfolio_not_found | 404 | ?portfolioId= غير موجود كمحفظة حية في مؤسستك. |
invalid_body | 400 | تعذّرت قراءة متن الطلب كنص. |
invalid_json | (لكل صف) | صف ليس JSON صالحًا. يظهر داخل مصفوفة errors[] لكل صف؛ وتُرجع الدفعة 200. |
الرمز غير الموجود في هذا المسرد يدل على أن المنصة أضافت رمزًا مسمّى جديدًا منذ آخر مراجعة لهذه الصفحة. سجّل دائمًا قيمة code حرفيًا إلى جانب خطأ تطبيقك ليتمكن الفريق الهندسي من الربط بينهما.
رموز الأخطاء لكل صف (المجمّع والاستيرادات غير المتزامنة)
يُرجع كلٌّ من NDJSON المجمّع والاستيرادات غير المتزامنة أخطاء لكل صف. تستخدم الواجهة المجمّعة مجموعة واحدة من القيم؛ وتستخدم واجهة الاستيرادات غير المتزامنة مجموعة مشابهة لكنها مختلفة قليلًا (فهي تتضمن على وجه الخصوص validation_error بدلًا من validation_failed، ما يعكس واجهة أقدم). تصف المدخلات لكل صف حالات فشل صفوف منفردة داخل دفعة ناجحة، لا حالات فشل الغلاف.
الرموز لكل صف في NDJSON المجمّع
| الرمز لكل صف | المُسبِّب |
|---|---|
validation_failed | فشل الصف في التحقق من المخطط. يحمل الحقل message أخطاء التحقق. |
fk_violation | مرجع مفتاح أجنبي في الصف (مثل borrowerId أو loanId) لا يشير إلى صف حي في المحفظة نفسها. |
unique_violation | يوجد بالفعل صف حي بالقيمة نفسها لـ (portfolio, externalId) أو id. (لا يوجد رمز منفصل id_conflict لكل صف؛ إذ يظهر كلا نوعَي تصادم معرّفات المستدعي هنا.) |
check_violation | فشلت قاعدة بيانات — عادةً قاعدة الإعفاء في دفعة. |
db_error | خطأ غير متوقع أثناء تخزين هذا الصف. يُبلَّغ عن الصف كفاشل؛ وتستمر الدفعة. |
invalid_json | الصف ليس JSON صالحًا. تعالج المنصة بقية الدفعة. |
الرموز لكل صف في الاستيرادات غير المتزامنة
| الرمز لكل صف | المُسبِّب |
|---|---|
parse_error | السطر ليس JSON صالحًا. |
validation_error | فشل الصف في التحقق من المخطط. |
portfolio_mismatch | لا يطابق portfolioId الخاص بالصف محفظة الارتكاز للاستيراد. |
processor_error | فشل غير متوقع في المعالج أثناء معالجة هذا الصف. |
تظهر الأخطاء التي تقع أثناء تخزين صف (مرجع مفقود، أو تكرار، أو قاعدة بيانات فاشلة) تحت أحد الرموز أعلاه مع التفاصيل في errorMessage.
لا تتصاعد الأخطاء لكل صف أبدًا إلى استجابة غير 200 على المستوى الأعلى من الواجهة المجمّعة — فالدفعة ككل قد نجحت إذا كان الطلب نفسه سليم الصيغة؛ وتخبرك الرموز لكل صف بما خُزّن.
دلالات إعادة المحاولة
النمط الآمن لإعادة المحاولة لأي مسار تعديل هو:
- ولّد
Idempotency-Keyحتميًا لكل عملية منطقية. ويصلح UUIDv4 مع مميّز للمسار. - أرسل الطلب مع المفتاح.
- عند أيٍّ من
2xx،409 ID_CONFLICT،409 IDEMPOTENCY_CONFLICT،409 IDEMPOTENCY_KEY_REUSED،404،403،400،413أو422— لا تُعِد المحاولة. النتيجة نهائية. - عند
429— أعِد المحاولة بعد المدة المذكورة في ترويسةRetry-After. - عند
500أو خطأ في الشبكة — أعِد المحاولة عددًا صغيرًا ثابتًا من المرات مع تراجع أُسّي. يجعلIdempotency-Keyإعادة المحاولة آمنة سواء وصلت المحاولة الأولى أم لا.
إعادة محاولة طلب ناجح بالمفتاح Idempotency-Key نفسه تُرجع الاستجابة نفسها التي أُرجعت في الأصل، مع reused: true على الكيان المعني. وهذا هو التعافي القياسي في المسار السعيد من انقطاع عابر في الشبكة.
ما لا تُرجعه المنصة أبدًا
لأغراض التصحيح التشغيلي، من المفيد معرفة الحيّز السلبي:
- لا تعامل المنصة أي رمز حالة
5xxعلى أنه ميزة. إن500دائمًا خلل ينبغي إصلاحه؛ فلا تكتب أبدًا منطقًا في العميل يعتمد على شكل500محدد. - لا تكشف أي استجابة
404الاستئجار. تبدو404لصف موجود في مؤسسة أخرى مطابقة تمامًا لـ404لصف غير موجود في أي مكان. فلا تكتب منطقًا في العميل يستنتج الوجود عبر المستأجرين. - لا تحمل أي استجابة ناجحة حقلًا في المتن باسم
success: false. رمز الحالة هو المصدر الموثوق لمعرفة ما إذا نجح الاستدعاء؛ ويحمل شكل المتن التفاصيل. - لا يُرجع أي مسار كتابة UUID الخاص به بأسلوب معامل المسار (ترويسة "Location"). يظهر UUID المُنشأ في الحقل
idمن متن الاستجابة.