نموذج الخطأ

يستخدم Asset Core رموز حالة HTTP القياسية مع استجابات أخطاء تفاصيل المشكلة RFC 9457. تصف هذه المرجعية نموذج الخطأ وظروف الخطأ الشائعة. تم تصميمها لتكون مستقرة حتى يتمكن العملاء من بناء منطق إعادة المحاولة والتصحيح المتوقع.

نظرة عامة

تُعاد الأخطاء كحمولات application/problem+json مع تصنيف مستقر، ورموز قابلة للقراءة الآلية، وإرشادات اختيارية لإعادة المحاولة. يشير رمز حالة HTTP إلى فئة الخطأ، بينما يوفر الجسم تفاصيل محددة. اعتبر حقل code كمعرف قياسي قابل للقراءة الآلية.

الهيكل

استجابة خطأ الكتابة/القراءة (تفاصيل المشكلة)

{
  "type": "urn:assetcore:error:CONTAINER_NOT_FOUND",
  "title": "NotFoundError",
  "status": 404,
  "detail": "Container 1001 not found",
  "code": "CONTAINER_NOT_FOUND",
  "retryable": false,
  "hint": "Verify the container ID",
  "server_correlation_id": "wr-0000000000000001-0000000000000042",
  "client_correlation_id": "client-req-2026-01-15",
  "details": {
    "container_id": 1001
  }
}

تفاصيل حقول الخطأ

الحقل	النوع	الوصف
`type`	سلسلة	نوع URI وفقًا لـ RFC 9457 (يستخدم Asset Core `urn:assetcore:error:\`CODE“)
`title`	سلسلة	اسم فئة الخطأ القصير (`ValidationError`, `NotFoundError`)
`status`	عدد صحيح	رمز حالة HTTP
`detail`	سلسلة	تفسير قابل للقراءة البشرية
`code`	سلسلة	معرف الخطأ القابل للقراءة الآلية (`SCREAMING_SNAKE_CASE`)
`retryable`	بولياني	ما إذا كان يجب على العملاء إعادة المحاولة
`retry_after_ms`	عدد صحيح	تلميح اختياري لإعادة المحاولة بعد في المللي ثانية (429/503)
`hint`	سلسلة	تلميح اختياري للإصلاح
`auth_reason`	سلسلة	سبب رفض المصادقة الاختياري (فقط عندما يكون الكشف هو `reason_code`)
`server_correlation_id`	سلسلة	معرف الارتباط المعين من قبل الخادم (اختياري)
`client_correlation_id`	سلسلة	معرف الارتباط المقدم من العميل (اختياري)
`details`	كائن	تفاصيل هيكلية اختيارية
`core_error`	كائن	حمولة خطأ أساسي مسلسلة اختيارية (للكتابة فقط)

حقول

رموز حالة HTTP

الحالة	المعنى	متى تستخدم
`200 OK`	نجاح	تم إكمال الطلب بنجاح
`400 Bad Request`	طلب غير صالح	JSON مشوه، حقول مفقودة
`401 Unauthorized`	غير مصادق عليه	مفقود أو رمز حامل غير صالح
`403 Forbidden`	غير مسموح	لا يمتلك المستخدم الإذن أو الوصول إلى مساحة الأسماء
`404 Not Found`	المورد غير موجود	الحاوية أو الفئة غير موجودة
`409 Conflict`	تعارض الحالة	تصادم مفتاح الاستقلالية، موجود بالفعل
`422 Unprocessable Entity`	فشل التحقق	لم يتم استيفاء شروط العملية
`425 Too Early`	قراءة قديمة	لم يتم الوصول إلى الحد الأدنى من تسلسل العالم (نقاط النهاية للقراءة)
`429 Too Many Requests`	محدودية المعدل	حدود الحصة أو حدود معدل المصادقة
`500 Internal Server Error`	خطأ في الخادم	فشل غير متوقع
`503 Service Unavailable`	غير متاح مؤقتًا	محمل بشكل زائد، يتم إيقاف التشغيل

رموز الأخطاء الشائعة

أخطاء الحاويات

الرمز	الحالة	الوصف
`CONTAINER_NOT_FOUND`	404	الحاوية المحددة غير موجودة
`CONTAINER_ALREADY_EXISTS`	409	معرف الحاوية قيد الاستخدام بالفعل
`WRONG_CONTAINER_KIND`	422	العملية غير مدعومة لهذا النوع من الحاويات

أخطاء التوازن

الرمز	الحالة	الوصف
`INVALID_QUANTITY`	422	يجب أن تكون الكمية أكبر من الصفر
`INSUFFICIENT_BALANCE`	422	رصيد غير كافٍ للعملية
`INVALID_OPERATION`	422	العملية ستتجاوز الحد أو غير صالحة

أخطاء المثيل

الرمز	الحالة	الوصف
`INSTANCE_NOT_FOUND`	404	المثيل المحدد غير موجود
`ALREADY_ATTACHED`	409	المثيل لديه بالفعل والد
`NOT_ATTACHED`	422	المثيل ليس لديه والد لفصله
`HAS_CHILDREN`	422	يجب فصل الأطفال قبل الحرق
`WOULD_CREATE_CYCLE`	422	الربط سيخلق دورة

أخطاء الفتحات

الكود	الحالة	الوصف
`SLOT_OUT_OF_BOUNDS`	422	فهرس الفتحة يتجاوز سعة الحاوية
`SLOT_OCCUPIED`	409	الفتحة تحتوي بالفعل على مثيل
`SLOT_EMPTY`	422	الفتحة لا تحتوي على مثيل

أخطاء المخطط

الرمز	الحالة	الوصف
`UNREGISTERED_CLASS`	404	الفئة المحددة غير مسجلة
`CLASS_ALREADY_EXISTS`	409	معرف الفئة مسجل بالفعل
`SHAPE_ALREADY_REGISTERED`	409	الشكل موجود بالفعل لهذه الفئة
`UNREGISTERED_CLASS_SHAPE`	422	الشكل مطلوب ولكنه غير مسجل

أخطاء النظام

الرمز	الحالة	الوصف
`INVALID_REQUEST`	400	JSON مشوه أو معلمات غير صالحة
`PAYLOAD_TOO_LARGE`	413	جسم الطلب يتجاوز الحدود المكونة
`UNSUPPORTED_MEDIA_TYPE`	415	نوع المحتوى ليس JSON
`INTEGER_OVERFLOW`	500	تجاوز عددي (خطأ)
`SERVICE_UNAVAILABLE`	503	النظام مثقل أو يتم إيقافه

أمثلة

طلب غير صحيح (400)

JSON غير صالح:

{
  "type": "urn:assetcore:error:INVALID_REQUEST",
  "title": "ValidationError",
  "status": 400,
  "detail": "Failed to parse JSON body",
  "code": "INVALID_REQUEST",
  "retryable": false,
  "details": {
    "position": 42,
    "expected": "string"
  }
}

غير موجود (404)

الحاوية غير موجودة:

{
  "type": "urn:assetcore:error:CONTAINER_NOT_FOUND",
  "title": "NotFoundError",
  "status": 404,
  "detail": "Container 1001 does not exist",
  "code": "CONTAINER_NOT_FOUND",
  "retryable": false,
  "details": {
    "container_id": 1001
  }
}

الصراع (409)

مفتاح التكرار قد تم استخدامه بالفعل بمحتوى مختلف:

{
  "type": "urn:assetcore:error:IDEMPOTENCY_CONFLICT",
  "title": "ConflictError",
  "status": 409,
  "detail": "Idempotency key 'create-1001' was used with different request content",
  "code": "IDEMPOTENCY_CONFLICT",
  "retryable": false,
  "details": {
    "idempotency_key": "create-1001"
  }
}

الكيان غير القابل للمعالجة (422)

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

{
  "type": "urn:assetcore:error:INSUFFICIENT_BALANCE",
  "title": "ValidationError",
  "status": 422,
  "detail": "Insufficient balance: requested 500, available 100",
  "code": "INSUFFICIENT_BALANCE",
  "retryable": false,
  "details": {
    "container_id": 1001,
    "class_id": 100,
    "key": 1,
    "requested": 500,
    "available": 100
  }
}

الخدمة غير متاحة (503)

نظام مثقل:

{
  "type": "urn:assetcore:error:SERVICE_UNAVAILABLE",
  "title": "UnavailableError",
  "status": 503,
  "detail": "System is at capacity, please retry later",
  "code": "SERVICE_UNAVAILABLE",
  "retryable": true,
  "retry_after_ms": 100,
  "details": {
    "queue_depth": 1000
  }
}

HTTP API - مرجع نقطة النهاية
المعاملات - هيكل الطلب
مرجع الإجراءات - أخطاء محددة بالعملية