رموز حالة HTTP متى تُرجع 404 أو 410 أو 301 (وأوقف التخمين)

أعادت إرسال 200 مع {"error": "user not found"} في الجسم. أنت تُرسل 301 بدلًا من 302. الموارد المُحذوفة تُرسل دائمًا 404. دعونا نمرّ بأساسيات الأكواد المرتبطة بالمستخدمين التي يخطئونها غالبًا، وما يجب أن تُرسله بدلًا من ذلك.

4xx مقابل 5xx: ليس نفس المجموعة

التمييز الأساسي في أكواد الحالة الخاصة بـ HTTP: 4xx هو خطأ من جانب العميل، 5xx هو خطأ من جانبك. بسيط نظرًا للنظرية، لكنه يُنتهك دائمًا في الممارسة.

الخطأ الأكثر شيوعًا: إرسال 500 لخطأ تحقق. أرسل العميل بيانات JSON غير صحيحة إلى واجهة برمجة تطبيقاتك. هذا هو 400 طلب غير صحيح — كان المحتوى غير صحيح. يُخبر العميل 500 بأنه "انهار النظام"، مما يُنشئ تنبيهات، يُسجل كخطأ على الخادم، ويُسبب أنظمة تلقائية لإعادة التحقق (ما يزيد من سوء الوضع). إذا أرسل العميل بيانات خاطئة، فقل ذلك بـ 4xx.

404 مقابل 410: مشكلة الموارد المُحذوفة

404 غير موجود يعني: "لا أملكها الآن، لكن حاول مرة أخرى لاحقًا." تُعامل المُستكشفات مثل Googlebot 404 كمُستحيل مؤقت. سيستمر في التحقق منها بشكل غير محدود.

410 مُختفي يعني: "تم حذف هذه الموارد بشكل دائم. لا تطلب منها أبدًا." يُزيل Googlebot المواقع المُحذوفة من الملف بشكل أسرع من 404، ويُوقف تصفحها أسرع. هذا مهم للتحسينات في محركات البحث وعوامل التصفح على المواقع الكبيرة.

القاعدة العملية: إذا حذفت واجهة برمجية مُستندًا وليست مُعادًا، فارسل 410 في الطلبات التالية. السبب الوحيد للاختيار بين 404 هو إذا كان من الممكن استعادة الموارد — مثل الحذف المُستقر مع فترة استعادة، مقال مُنشور يمكن إعادة نشره، إلخ. أما في غير ذلك، فإن 410 أكثر صدقًا وستشكر محركات البحث على ذلك.

301 مقابل 302 (وسبب وجود 307/308)

301 مُحَوَّل دائمًا: هذا الرابط مُختفي دائمًا، استخدم الرابط الجديد. تُخزن المتصفحات 301 بشكل مكثف. تنقل محركات البحث القيمة المرتبطة بالرابط إلى الوجهة. إذا كنت تُدمج مجالات أو تُنقل موقعًا بشكل دائم، فهذا هو ما تريده.

302 مُعثر: اذهب إلى هذا الرابط الآن، لكن عد إلى الموضع الأصلي لاحقًا. لا تُخزن. لا تنقل القيمة المرتبطة بالرابط. استخدمه للإحالة أثناء تسجيل الدخول، أو الصفحات المؤقتة للصيانة، أو التجارب المُختبرة.

الوضع الخاطئ: استخدام 302 للإحالة الدائمة. تظن "نفس الشيء، فقط مختلف"، لكن محركات البحث لا تنقل القيمة المرتبطة بالرابط عبر 302. تبقى سنوات من العمل في تحسين محركات البحث مُرتبطًا بالرابط القديم، بينما يُصنف الرابط الجديد كمُستحيل. إذا قمت بتحويل شيء بشكل دائم، فاستخدم 301.

ثم هناك 307 إعادة توجيه مؤقت و 308 إعادة توجيه دائمة. هذه أشكال مُستقرة للطريقة: حيث قد يُخفض المتصفح POST إلى GET عند الانتقال عبر 301/302، أما 307/308 فتُحافظ على الطريقة الأصلية. إذا كنت تُحول نقاط واجهة برمجية تقبل محتوى POST، فتُحافظ 307 (مُستقرة مؤقتًا) أو 308 (مُستقرة دائمًا) على الطريقة الأصلية.

شفرة	يكتب	الكشوفات؟	تُحافظ على الطريقة؟	استخدمها للـ
301	مُستقرة	نعم	لا (قد يُخفض إلى GET)	الإحالة الدائمة للمواقع، تجميع الروابط
302	مُستقرة مؤقتة	لا	لا (قد يُخفض إلى GET)	إحالة تسجيل الدخول، صفحات عدم التوفر المؤقت
307	مُستقرة مؤقتة	لا	نعم	إحالة مؤقتة للنطاقات POST في واجهة برمجية
308	مُستقرة	نعم	نعم	إحالة دائمة للنطاقات POST في واجهة برمجية

401 مقابل 403: التحقق من الهوية مقابل التصاريح

الإسماء مُضطربة. 401 غير مصرح به يعني بالفعل غير مُصادق عليه — لم تُسجل بتسجيل دخول، أو معلومات التحقق مفقودة أو غير صالحة. 403 ممنوع يعني أنك مُصادق عليه، لكنك لا تمتلك صلاحية للوصول إلى هذا المورد.

الفرق العملي: يجب أن يُطلب من 401 عرض شاشة تسجيل دخول أو تجديد التذكرة. يجب أن يُعرض 403 رسالة "الوصول ممنوع". إذا أرسلت القيمة الخاطئة، فلن يعلم العميل ما إذا كان يجب أن يطلب التسجيل أو يُنهي.

هناك أيضًا جانب أمني. بعض الواجهات تُرسل 404 بدلًا من 403 للموارد التي لا يمكن للمسجل الوصول إليها، لتجنب تسريب أن المورد موجود. إذا أرسلت 403 على مورد من طرف آخر، فتم تأكيد وجوده. أما 404 فهو أكثر أمانًا من حيث المعلومات، رغم أنه يجعل التصحيح أكثر صعوبة للأشخاص المُسموح لهم. اختر التوازن المناسب وفقًا لنموذج التهديد وطبقه بشكل متسق.

429: التقييد بالسرعة، مع الرأس المفيد

أي رأس بسيط 429 طلبات زائدة مُزعج. رأس 429 مع Retry-After مفيد حقًا.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1746374400

Retry-After يمكن أن يكون عددًا من الثواني أو تاريخًا HTTP. سيعمل المُستخدمون المُحسّنون تلقائيًا على التراجع. بدونه، فإنك تُرسل رمز خطأ وترغب أن يُكتشف من قبل العميل متى يجب إعادة التحقق — معظمهم سيُعيد التحقق من نفس النقطة فورًا، مما يُبطل هدف التقييد بالسرعة.

لا تُرسل 503 للقيود على السرعة. 503 يعني "غير متاح" — الخدمة مُغلقة، أو في حالة تطوير، أو مُغلق بالكابل. التقييد على السرعة هو قرار سياسة، وليس فشل في الخدمة. 429 موجود بالضبط لهذا السبب.

النمط الخاطئ: "200 مع جسم خطأ"

هذا يظهر بشكل متكرر في واجهات برمجة تطبيقات الإنتاج ويجب أن يُوقف:

HTTP/1.1 200 OK
Content-Type: application/json

{"status": "error", "message": "user not found"}

هذا يُهدد كل ما يعتمد على مبادئ HTTP. تُبلغ الأدوات المراقبة عن الطلب كمُتَّسِق. تمرّ الـ Load Balancers به. لا تُرسل المكتبات العميلة. تبدو السجلات نظيفة بينما يرى المستخدمون أخطاء. الحل هو سطر واحد: أرسل الرمز الصحيح للحالة. 200 يعني أن العملية نجحت. إذا لم تنجح، فلا تُرسل 200.

يُطبّق نفس المنطق على 201 مقابل 200 للإنشاء. إذا كان POST إلى /users يُنشئ مستخدمًا جديدًا، فارسل 201 مُنشأ . قبل التحويل إلى JSON، غالبًا ما ترغب في استخراج المحتوى فقط. Location مُشير إلى المورد الجديد. إذا أرسلت 200، فقد قمت بفقدان معلومات يمكن استخدامها من قبل العميل لتجنب طلب إضافي.

موقف واجهة برمجية → الرمز الصحيح للحالة

إليك جدولًا مرجعيًا للحالات التي تظهر غالبًا في تطوير واجهة برمجية REST:

سيناريو	رمز الحالة	ملحوظات
محتوى الطلب غير صحي	400 طلب غير صحيح	أضف رسالة تشير إلى خطأ التحليل
مجال مفقود أو غير صالح في الطلب	422 كيان غير قابل للتنفيذ	422 أكثر دقة من 400 للإخفاقات في التحقق من المعنى
مفتاح التحقق مفقود أو منتهي الصلاحية	401 غير مصرح به	يُضاف WWW-Authenticate رأس
مُصادق عليه لكن لا يملك صلاحية	403 ممنوع	أو 404 إذا كان التخفي من وجود المورد هو شرطًا
مورد غير موجود، قد تُرجع	404 غير موجود	للاختفاء المؤقت أو الموارد غير المعروفة
مورد مُحذوف بشكل دائم	410 مُختفي	سيتوقف المُستكشفون عن التحقق منه أسرع
تم إنشاء مورد جديد	201 مُنشأ	إضافة Location: /resources/new-id رأس
حذف نجح، لا يوجد جسم	204 لا يوجد محتوى	لا تُرسل جسمًا فارغًا مع 200
تغيير رابط دائم	301 مُحَوَّل دائمًا	تُنقل القيمة المرتبطة بالرابط إلى الوجهة
توجيه مؤقت	302 مُعثر	لا تُخزن، لا تنقل القيمة المرتبطة بالرابط
تم تجاوز الحد المسموح به للسرعة	429 طلبات زائدة	أضف دائمًا Retry-After
خطأ خادم غير متوقع	500 خطأ داخلي في الخادم	لا تُعرض تفاصيل السلاسل في الجسم
الاعتماد المُستند مُغلق	503 غير متوفر	إضافة Retry-After إذا كان التوقف محدودًا
إحالة POST، حافظ على الطريقة	307 أو 308	307 مؤقت، 308 دائم

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

التحقق من سلسلة الإحالة

بعد نقل الموقع أو إعادة هيكلة الروابط، من المهم التحقق من سلسلة الإحالة الكاملة — خاصة إذا كانت هناك 301 تم تغييرها لتنقل إلى مكان آخر، مما يخلق سلسلة متعددة الدرجات تُفقد القيمة المرتبطة بالرابط. فإن مُحرِّر المُرَاجَع يُتبع السلسلة ويُظهر كل رمز الحالة تباعًا، بحيث يمكنك التأكد من أن كل شيء يُحل في خطوة واحدة.

قد يعجبك أيضاً