نموذج الخطأ

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

نظرة عامة

تُعاد الأخطاء ككائنات JSON تحتوي على تفاصيل حول ما فشل ولماذا. يشير رمز حالة HTTP إلى فئة الخطأ، بينما يوفر الجسم تفاصيل محددة.

الهيكل

إرشادات إضافية:

النبرة: رسمية
السجل: تقني

السياق:

• المجال: بنية تحتية للبلوكشين
• الجمهور: مهندسو الأمن وقادة البنية التحتية
• الغرض: وثائق تقنية
• اللغة: ar
• الاتجاه: RTL

القيود:

• استخدام لغة محايدة للجنس
• الحفاظ على أسماء العلامات التجارية
• الحفاظ على الدقة التقنية
• ضمان أن تظل علامات الترقيم والترقيم مناسبة للاتجاه RTL
• الحفاظ على أسماء العلامات التجارية والمصطلحات في القاموس دون ترجمة

الحفاظ على دون ترجمة:

• code_blocks
• inline_code
• الروابط
• glossary_terms
• الملاحظات الرياضية

إرشادات القاموس:

الحفاظ على هذه المصطلحات بالضبط (لا تترجم): Asset Core، Asset‑Core، CSP، API، Docker، ECS، daemon، L1، L2، L3، OpenGraph، GitHub، Astro، TypeScript، JavaScript، ℤ، ℤ²، ℤ³، ℝ²، ℝ³، 0D، 1D، 2D، 3D

استجابة الخطأ

{
  "error": {
    "code": "ErrorCode",
    "message": "Human-readable description",
    "details": {
      "field": "additional context"
    }
  }
}

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

الحقل	النوع	الوصف
code	سلسلة	معرف خطأ قابل للقراءة الآلية
message	سلسلة	وصف قابل للقراءة البشرية
details	كائن	سياق إضافي (يختلف حسب الخطأ)
operation_index	عدد صحيح	أي عملية فشلت (للمعاملات)

الحقول

رموز حالة HTTP

الحالة	المعنى	متى تستخدم
200 OK	نجاح	تم إكمال الطلب بنجاح
400 Bad Request	طلب غير صالح	JSON مشوه، حقول مفقودة
404 Not Found	المورد غير موجود	الحاوية أو الفئة غير موجودة
409 Conflict	تعارض الحالة	تصادم مفتاح التكرار، موجود بالفعل
422 Unprocessable Entity	فشل التحقق	لم يتم استيفاء شروط العملية
500 Internal Server Error	خطأ في الخادم	فشل غير متوقع
503 Service Unavailable	غير متاح مؤقتًا	تحميل زائد، إيقاف التشغيل

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

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

الرمز	الحالة	الوصف
ContainerNotFound	404	الحاوية المحددة غير موجودة
ContainerAlreadyExists	409	معرف الحاوية قيد الاستخدام بالفعل
WrongContainerKind	422	العملية غير مدعومة لهذا النوع من الحاويات

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

الرمز	الحالة	الوصف
InvalidQuantity	422	يجب أن تكون الكمية أكبر من الصفر
InsufficientBalance	422	رصيد غير كافٍ للعملية
InvalidOperation	422	العملية ستتجاوز الحدود أو غير صالحة

أخطاء المثيل

الرمز	الحالة	الوصف
InstanceNotFound	404	المثيل المحدد غير موجود
AlreadyAttached	409	المثيل لديه والد بالفعل
NotAttached	422	المثيل ليس لديه والد لفصله
HasChildren	422	يجب فصل الأطفال قبل الحرق
WouldCreateCycle	422	الربط سيخلق دورة

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

الرمز	الحالة	الوصف
SlotOutOfBounds	422	مؤشر الفتحة يتجاوز سعة الحاوية
SlotOccupied	409	الفتحة تحتوي بالفعل على مثيل
SlotEmpty	422	الفتحة لا تحتوي على مثيل

أخطاء المخطط

الرمز	الحالة	الوصف
ClassNotFound	404	الفئة المحددة غير مسجلة
ClassAlreadyExists	409	معرف الفئة مسجل بالفعل
ShapeAlreadyDefined	409	معرف الشكل موجود بالفعل لهذه الفئة
UnregisteredClassShape	422	الشكل مطلوب ولكنه غير مسجل

أخطاء النظام

الرمز	الحالة	الوصف
ParseError	400	JSON غير صالح في جسم الطلب
ValidationError	422	فشل التحقق من صحة الطلب
IntegerOverflow	422	العملية العددية ستتجاوز الحد
ServiceUnavailable	503	النظام مثقل أو في حالة إيقاف التشغيل

أمثلة

إرشادات إضافية:

النبرة: رسمية السجل: تقني

السياق:

• المجال: بنية تحتية للبلوك تشين
• الجمهور: مهندسو الأمان وقادة البنية التحتية
• الغرض: وثائق تقنية
• اللغة: ar
• الاتجاه: من اليمين إلى اليسار

القيود:

• استخدام لغة محايدة للجنس
• الحفاظ على أسماء العلامات التجارية
• الحفاظ على الدقة التقنية
• ضمان أن تظل علامات الترقيم والترقيم مناسبة من حيث الاتجاه
• الحفاظ على أسماء العلامات التجارية والمصطلحات غير مترجمة

الحفاظ على دون ترجمة:

• code_blocks
• inline_code
• links
• glossary_terms
• mathematical_notation

إرشادات المصطلحات:

الحفاظ على هذه المصطلحات بالضبط (لا تترجم): Asset Core, Asset‑Core, CSP, API, Docker, ECS, daemon, L1, L2, L3, OpenGraph, GitHub, Astro, TypeScript, JavaScript, ℤ, ℤ², ℤ³, ℝ², ℝ³, 0D, 1D, 2D, 3D

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

JSON غير صالح:

{
  "error": {
    "code": "ParseError",
    "message": "Failed to parse JSON body",
    "details": {
      "position": 42,
      "expected": "string"
    }
  }
}

غير موجود (404)

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

{
  "error": {
    "code": "ContainerNotFound",
    "message": "Container 1001 does not exist",
    "details": {
      "container_id": 1001
    }
  }
}

الصراع (409)

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

{
  "error": {
    "code": "IdempotencyConflict",
    "message": "Idempotency key 'create-1001' was used with different request content",
    "details": {
      "idempotency_key": "create-1001"
    }
  }
}

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

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

{
  "error": {
    "code": "InsufficientBalance",
    "message": "Insufficient balance: requested 500, available 100",
    "details": {
      "container_id": 1001,
      "class_id": 100,
      "key": 1,
      "requested": 500,
      "available": 100
    },
    "operation_index": 0
  }
}

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

نظام مثقل:

{
  "error": {
    "code": "ServiceUnavailable",
    "message": "System is at capacity, please retry later",
    "details": {
      "queue_depth": 1000,
      "retry_after_ms": 100
    }
  }
}

المراجع ذات الصلة

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