أكواد الخطأ - توثيق API

صيغة استجابة الخطأ

تستخدم جميع استجابات الأخطاء صيغة موحدة:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "رسالة خطأ قابلة للقراءة البشرية",
    "details": "سياق إضافي (اختياري)"
  }
}

💡 استخدم error.code كشرط فرعي ثابت (قد تتغير رسالة الخطأ)

رموز حالة HTTP

200 OK

نجح الطلب

200

201 Created

تم إنشاء المورد بنجاح

201

400 Bad Request

معاملات الطلب غير صالحة

400

{
  "code": "INVALID_REQUEST",
  "message": "صيغة الطلب غير صالحة"
}

401 Unauthorized

لم تتم المصادقة أو مفتاح API غير صالح

401

{
  "code": "UNAUTHORIZED",
  "message": "مفتاح API غير صالح أو منتهي الصلاحية"
}

403 Forbidden

رصيد الحساب غير كافٍ أو لا توجد أذونات

403

{
  "code": "INSUFFICIENT_BALANCE",
  "message": "رصيد الحساب غير كافٍ"
}

404 Not Found

المورد غير موجود

404

{
  "code": "ORDER_NOT_FOUND",
  "message": "الطلب غير موجود"
}

409 Conflict

تعارض في المورد

409

{
  "code": "ADDRESS_EXISTS",
  "message": "العنوان موجود بالفعل"
}

429 Too Many Requests

تجاوز حد معدل مفتاح API

429

{
  "code": "RATE_LIMITED",
  "message": "تم تجاوز حد المعدل"
}

500 Internal Server Error

خطأ داخلي في الخادم

500

{
  "code": "INTERNAL_ERROR",
  "message": "حدث خطأ غير متوقع"
}

503 Service Unavailable

الخدمة غير متاحة مؤقتًا (جارٍ الصيانة)

503

{
  "code": "SERVICE_UNAVAILABLE",
  "message": "الخدمة غير متاحة مؤقتًا"
}

أكواد الأخطاء الشائعة

Error Code	Status	Description	Solution
UNAUTHORIZED	401	مفتاح API غير صالح أو منتهي الصلاحية أو ملغى	تحقق من أن مفتاح API صحيح، قم بإنشاء واحد جديد إذا لزم الأمر
INSUFFICIENT_BALANCE	403	رصيد الحساب غير كافٍ	إعادة شحن الحساب
INVALID_ADDRESS	400	صيغة عنوان TRON غير صالحة	تحقق من أن العنوان هو عنوان TRON صالح (يبدأ بـ T)
INVALID_ENERGY_AMOUNT	400	كمية الطاقة غير صالحة	يجب أن تكون كمية الطاقة عددًا صحيحًا موجبًا، يُنصح بـ 65000 لتحويل USDT
INVALID_DURATION	400	مدة التأجير غير صالحة	استخدم مدة صالحة: 1H، 1D، 3D، 7D، 14D، 30D
ORDER_NOT_FOUND	404	لا يوجد طلب	تحقق من أن معرف الطلب صحيح
ADDRESS_EXISTS	409	العنوان موجود بالفعل	تحقق من أن العنوان قد تمت إضافته بالفعل أو استخدم العنوان الموجود
RATE_LIMITED	429	تجاوز حد معدل مفتاح API (ينطبق حاليًا فقط على POST /v1/wallet/recharges)	أعد المحاولة باستخدام تأخير تصاعدي أو قلل معدل الطلبات

طرق المعالجة

Error	Handling
401 UNAUTHORIZED	التحقق من/تدوير مفتاح API
403 INSUFFICIENT_BALANCE	إعادة الشحن أو تقليل الكمية المطلوبة
409 ADDRESS_EXISTS	التبديل إلى الاستعلام/المعالجة الثابتة
429 RATE_LIMITED	إعادة المحاولة مع انتظار (اتبع Retry-After إن وجد، وإلا استخدم تأخير تصاعدي)
5xx	إعادة المحاولة + تسجيل سياق الطلب

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

• الحد الأقصى لإعادة المحاولة: 3 مرات
• الانتظار: تصاعدي (1 ثانية، 2 ثانية، 4 ثواني...)
• إعادة المحاولة فقط مع 429/5xx
• لا تعيد المحاولة مع 4xx (أخطاء من جانب العميل)

أكواد الخطأ والمعالجة