Waafir
هذه الصفحة ترجمة آلية في انتظار المراجعة البشرية. قد تحتوي على أخطاء.

الأخطاء ورموز الحالة

هذه الصفحة هي المرجع الموحّد لأغلفة الاستجابة التي يستخدمها كل مسار في واجهة 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" }
  ]
}
الحقلالنوعملاحظات
errorstringملخص قصير مقروء للبشر.
fieldErrors[].pathstringالمسار المنقّط إلى الحقل المخالف. تشير (root) إلى المتن نفسه، مثلًا عند فشل تحليل JSON.
fieldErrors[].messagestringشرح مقروء للبشر.

تُصدر بعض المسارات 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" }
  ]
}
الحقلالنوعملاحظات
errorstringملخص مقروء للبشر.
codestringرمز ثابت مقروء آليًا؛ راجع المسرد.
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_CONFLICT409POST /borrowers، POST /loans، POST /payments.يوجد بالفعل صف حي بالقيمة نفسها لـ id.
PORTFOLIO_NOT_FOUND404كل مسارات الكتابة للسجل الواحد.portfolioId الوارد في المتن غير موجود في مؤسستك.
REFERENCED_ENTITY_NOT_FOUND422POST /loans، POST /payments.يشير borrowerId أو loanId إلى صف غير موجود كصف حي في المحفظة نفسها.
INVALID_STATUS_TRANSITION422PATCH /loans/{loanRef}/status.زوج حالتَي المصدر/الوجهة غير موجود في مصفوفة الانتقالات.
IDEMPOTENCY_CONFLICT409PATCH /loans/{loanRef}/status.سبق استخدام Idempotency-Key لانتقال حالة مختلف. أرسل الانتقال الجديد بمفتاح جديد.
IDEMPOTENCY_KEY_REUSED409POST /imports.سبق استخدام Idempotency-Key لاستيراد بمعاملات طلب مختلفة (kind، filename، sizeBytes، …). تتضمن الاستجابة importId وmismatchedFields. أرسل الاستيراد الجديد بمفتاح جديد.
MONITORING_INVESTOR_FORBIDDEN403جميع مسارات القروض في المراقبة، بما فيها مسارات NDJSON المجمّع.المستدعي حساب مستثمر؛ ولا يمكن للمستثمرين استخدام واجهة بيانات المراقبة البرمجية.
CHECK_VIOLATION400POST /payments.فشلت قاعدة بيانات (عادةً ثابت الإعفاء؛ إذ ترفض طبقة المخطط الشكل نفسه وقت التحقق).
NOT_FOUND404GET /borrowers/{id}، GET /payments/{id}، PATCH /loans/.../status، POST /payments/{id}/cancel، GET /loans/{externalId}.الصف المطلوب غير موجود كصف حي في النطاق المقدَّم، أو ينتمي إلى مؤسسة أخرى.
UNKNOWN_KIND400POST /imports.kind ليس واحدًا من أنواع القروض الستة. تتضمن الاستجابة مصفوفة allowed.
COMMIT_FAILED409POST /imports/{id}/commit.لم تتمكن المنصة من العثور على الملف المرفوع؛ وعادةً لم يكتمل الرفع. أعِد الرفع، ثم أعِد الالتزام.

فضاء رموز NDJSON المجمّع

الرمزالحالةالمُسبِّب
batch_too_large413يتجاوز المتن 10 000 صف أو 10 MB. يميّز error وfieldErrors[].message بين حد الصفوف وحد البايتات.
portfolio_id_required400?portfolioId=<UUID> مفقود أو ليس UUID صالحًا.
portfolio_not_found404?portfolioId= غير موجود كمحفظة حية في مؤسستك.
invalid_body400تعذّرت قراءة متن الطلب كنص.
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 على المستوى الأعلى من الواجهة المجمّعة — فالدفعة ككل قد نجحت إذا كان الطلب نفسه سليم الصيغة؛ وتخبرك الرموز لكل صف بما خُزّن.

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

النمط الآمن لإعادة المحاولة لأي مسار تعديل هو:

  1. ولّد Idempotency-Key حتميًا لكل عملية منطقية. ويصلح UUIDv4 مع مميّز للمسار.
  2. أرسل الطلب مع المفتاح.
  3. عند أيٍّ من 2xx، 409 ID_CONFLICT، 409 IDEMPOTENCY_CONFLICT، 409 IDEMPOTENCY_KEY_REUSED، 404، 403، 400، 413 أو 422 — لا تُعِد المحاولة. النتيجة نهائية.
  4. عند 429 — أعِد المحاولة بعد المدة المذكورة في ترويسة Retry-After.
  5. عند 500 أو خطأ في الشبكة — أعِد المحاولة عددًا صغيرًا ثابتًا من المرات مع تراجع أُسّي. يجعل Idempotency-Key إعادة المحاولة آمنة سواء وصلت المحاولة الأولى أم لا.

إعادة محاولة طلب ناجح بالمفتاح Idempotency-Key نفسه تُرجع الاستجابة نفسها التي أُرجعت في الأصل، مع reused: true على الكيان المعني. وهذا هو التعافي القياسي في المسار السعيد من انقطاع عابر في الشبكة.

ما لا تُرجعه المنصة أبدًا

لأغراض التصحيح التشغيلي، من المفيد معرفة الحيّز السلبي:

  • لا تعامل المنصة أي رمز حالة 5xx على أنه ميزة. إن 500 دائمًا خلل ينبغي إصلاحه؛ فلا تكتب أبدًا منطقًا في العميل يعتمد على شكل 500 محدد.
  • لا تكشف أي استجابة 404 الاستئجار. تبدو 404 لصف موجود في مؤسسة أخرى مطابقة تمامًا لـ 404 لصف غير موجود في أي مكان. فلا تكتب منطقًا في العميل يستنتج الوجود عبر المستأجرين.
  • لا تحمل أي استجابة ناجحة حقلًا في المتن باسم success: false. رمز الحالة هو المصدر الموثوق لمعرفة ما إذا نجح الاستدعاء؛ ويحمل شكل المتن التفاصيل.
  • لا يُرجع أي مسار كتابة UUID الخاص به بأسلوب معامل المسار (ترويسة "Location"). يظهر UUID المُنشأ في الحقل id من متن الاستجابة.