دليل استخدام رموز الحالة في REST API

يقدّم معايير عملية لاختيار رمز الحالة المناسب لكل حالة في REST API.

تُبلّغ REST API المصمّمة جيدًا عن نتيجة الطلب بوضوح عبر رموز الحالة. استخدم 200 OK للقراءة الناجحة، و201 Created لإنشاء مورد (مع وضع الـ URL الجديد في ترويسة Location)، و204 No Content للنجاح الذي لا يتضمّن جسمًا يُعاد (مثل الحذف).

تُميَّز أخطاء العميل برموز 4xx. فالمعيار هو 400 Bad Request للصياغة الخاطئة، و401 Unauthorized عند الحاجة إلى المصادقة، و403 Forbidden عند انعدام الصلاحية، و404 Not Found للمورد غير الموجود، و409 Conflict لتعارض الحالة، و422 Unprocessable Content لفشل التحقّق، و429 Too Many Requests لكثرة الطلبات.

ويُبلَّغ عن أخطاء الخادم برموز 5xx. استخدم 500 Internal Server Error للاستثناء غير المتوقّع، و503 Service Unavailable للحمل الزائد أو الصيانة، مع إرسال ترويسة Retry-After معه إن أمكن. والأهمّ أن إعادة الرمز نفسه دائمًا وباتّساق للحالة نفسها هي ما يحدّد سهولة استخدام الـ API.