أخطاء API

يُبلّغ API عن الأخطاء بأكواد حالة HTTP القياسية وجسم استجابة موحد. تُعيد الاستجابات الناجحة البيانات مباشرةً دون غلاف.

صيغة الخطأ

عند وقوع خطأ، يكون جسم الاستجابة كائن JSON يحتوي على حقل واحد error يتضمن رسالة يمكن للإنسان قراءتها:

{"error":"reaction not found"}

استند أولاً إلى كود حالة HTTP، واستخدم نص error للسجلات والتلميحات للمستخدم.

أكواد الحالة

  • 200 OK — الطلب ناجح، البيانات في الجسم.
  • 201 Created — أُنشئ مورد جديد (بعض نقاط POST).
  • 204 No Content — نجاح بدون جسم (بعض حالات الحذف).
  • 400 Bad Request — جسم أو معاملات طلب غير صحيحة.
  • 401 Unauthorized — الرمز غائب أو غير صحيح أو منتهي الصلاحية؛ أو المسار غير متاح عبر الرمز الشخصي.
  • 402 Payment Required — الإجراء يصطدم بقيود الخطة أو الحصة (مثلاً، مساحة تخزين الوسائط الخاصة تتطلب premium).
  • 403 Forbidden — الرمز لا يمتلك النطاق المطلوب لهذا المسار.
  • 404 Not Found — المورد غير موجود أو لا ينتمي إليك.
  • 409 Conflict — تعارض في الحالة (مثلاً، تكرار قيمة فريدة).
  • 422 Unprocessable Entity — الجسم صحيح صياغياً لكنه لا يجتاز التحقق من صحة المجال.
  • 429 Too Many Requests — تجاوز حد معدل الطلبات (راجع الحدود).
  • 500 Internal Server Error — خطأ داخلي في الخادم؛ أعد المحاولة لاحقاً.

كيفية المعالجة

اعتبر أكواد 2xx نجاحاً. عند 401/403 تحقق من الرمز ونطاقاته. عند 4xx (عدا 429) لا تعد الطلب دون تعديل — أصلح الطلب. عند 429 و5xx يناسب الأمر إعادة المحاولة مع تأخير أسي.

الخطوات التالية