كودات حالة HTTP التي تُلقي بسَلَمك — 301 مقابل 302، 401 مقابل 403، والمنطقة الخطرة من الكودات 5xx

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

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

301 مقابل 302 مقابل 307 مقابل 308: مصفوفة التوجيهات

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

301 هو دائم ويعمل على تخزينه بقوة. تُحدد المتصفحات فترة انتهاء التخزين المؤقت للاتجاه المحفوظ إلى ما يُعتبر لا نهائيًا إلا إذا قمت بوضع Cache-Control رأسية. لا يوجد طريقة برمجية لإنهاء التخزين المؤقت من متصفح المستخدم. إذا كنت تُفكر في هيكلة عنوان URL، استخدم 302.

المسألة المتعلقة بحفظ طريقة الاتجاه هي شيء مختلف. عندما يُتبع توجيه 301 أو 302، قد يُخفض المتصفح أو في الممارسة، يفعل ذلك دائمًا، توجيه POST إلى GET في الاتجاه. هذا يُعد انتهاكًا تقنيًا للوائح الأصلية لـ HTTP/1.0، لكن المتصفحات أخذت هذا التصحيح منذ زمن بعيد، وتم تأكيده في RFC 7231 كسلوك معياري. إذا كنت تُوجّه POST — مثل بعد إرسال نموذج — وترغب في الحفاظ على طريقة الاتجاه، فتحتاج إلى 307 أو 308. (ومن الناحية العملية، فإنها تُخفض تقريبًا دائمًا إلى GET أثناء التوجيه). هذا يُعد انتهاكًا تقنيًا للوائح الأصلية لـ HTTP/1.0، ولكن بذل المتصفحات تطويرًا مبكرًا لهذه الميزة، لذا يعترف RFC 7203 بوجودها كسلوك معياري. إذا كنت توجه طلبًا POST — مثل ما يحدث بعد إرسال نموذج — وترغب في الحفاظ على طريقة الطلب، فتحتاج إلى 307 أو 308.

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

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

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

401 تعني "لم تُعرف هويتك". تطلب المواصفات أن يحتوي على WWW-Authenticate رأسية تُخبر العميل كيف يُتحقق من الهوية. هذا هو الكود الصحيح عندما لا توجد جلسة صالحة، أو لا يوجد تذكرة، أو تذكرة قد انتهت.

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

الحجة الأمنية لعرض 404 بدلًا من 403 هي حقيقية. إذا عرضت API 403 على GET /admin/users، فلقد أخبرت أي مهاجم أن النقطة موجودة وأنه يحتاج إلى صلاحيات أعلى للوصول إليها. عرض 404 بدلًا من ذلك لا يُكشف أي معلومات عن وجود المورد. هذا هو قرار مبني على السياق: 403 هو منطقيًا صحيح وسهل التدقيق؛ 404 هو الخيار الآمن للنطاقات الحساسة حيث يُهم البقاء مجهولًا.

429: التقييد على السرعة لا يكون فعالًا بدون Retry-After

استجابة 429 بدون Retry-After رأسية هي علامة مغلقة. يعلم العميل أن التقييد حدث. لا يعرف ما إذا كان يجب الانتظار 100 مللي ثانية أو 24 ساعة. معظم تطبيقات العميل تعيد المحاولة فورًا (تُضغط على مُحدد التقييد) أو تُنهي بالكامل.

Retry-After تُأخذ إما عدد صحيح (الثواني التي يجب الانتظار) أو تاريخ HTTP (الوقت الذي يجب التحقق منه):

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

ال X-RateLimit-* الرؤوس ليست موجودة في أي معيار RFC — هي معيار غير رسمي من واجهة GitHub التي تم نسخها من قبل الجميع. أضفها مع Retry-After. المجموعة الثلاثية من Limit/Remaining/Reset تُخبر العميل عن وضعه قبل أن يصل إلى الحد، وهو أكثر ملاءمة من مجرد معرفة أنه وصل إلى الحد.

شيء يستحق الإشارة إليه: Retry-After مُسموح به أيضًا على استجابات 503، ويعني نفس الشيء — "أعود بعد هذه الثواني". إذا كان خدمةك غير متاحة مؤقتًا لفترة الصيانة، فارسل 503 مع Retry-After بدلًا من مجرد إغلاق الاتصال.

503 مقابل 504: أين تقع الفشل؟

هذان يشبهان بعضهما البعض لكنهما يشيران إلى طبقات فشل مختلفة، وخلطهما يُوجهك إلى الاتجاه الخاطئ في التدقيق.

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

504 تأخير في البوابة يعني أن باب التوجيه أو البوابة (مثلاً موزع الأحمال، nginx، بوابة API، CDN) حاول الوصول إلى خادم أعلى وحصل على استجابة في الوقت المحدد. الخادم الذي وصلت إليه هو نشط. المُستوى الذي وراءه لا يُجيب.

في الممارسة: إذا كنت وراء nginx وتم توقف خادم التطبيق (مثل Node، Rails، Django، أي شيء)، فتظهر لك 502 Bad Gateway — nginx حصل على استجابة لكنها كانت غير صالحة. إذا توقف خادم التطبيق عن الرد تمامًا، فتظهر لك 504. إذا عدت إلى خطأ من طبقة التطبيق، فتظهر لك 503. التمييز مهم عند التدقيق: 504 يعني أن تحقق من الخدمة العليا، إعدادات الانتظار، وشبكة الاتصال. 503 يعني أن تحقق من التطبيق نفسه.

422 مقابل 400: أخطاء التحقق لها كود خاص

400 طلب غير صحيح مخصص للطلبات التي لا يمكن للخادم تحليلها — مثل بيانات JSON غير صحيحة، أو تسلسل الاستعلام غير صحيح، أو غياب رؤوس مطلوبة. هذه مشكلة هيكلية.

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

تُستخدم معظم الأنظمة لدمج كلاهما في 400 وتحبس تفاصيل التحقق في جسم الاستجابة. هذا يعمل، لكنه يجعل معالجة الأخطاء في العميل صعبًا: يجب على العميل تحليل الجسد لتحديد ما إذا كان خطأ تحليل أو خطأ تحقق. استخدام 422 للاختبارات يسمح للعملاء بالاعتماد على كود الاستجابة. أداة رايلز فعلت ذلك بشكل صحيح منذ زمن بعيد؛ أيضًا، معيار JSON:API يحدد 422 للاختبارات.

النقطة الوحيدة: 422 مُعرّف في WebDAV (RFC 4918)، وليس في المواصفات الأساسية لـ HTTP. في الممارسة لا يهم — كل متصفح وخدمة HTTP تتعامل معه بشكل جيد — لكنك ستجد أحيانًا شخصًا صارمًا يصر على استخدام 400 بدلًا من ذلك. ليسوا خاطئين تمامًا. لكن 422 أكثر تحديدًا وفهمًا.

204 مقابل 200 مع جسم فارغ: واحد هو الصحيح لـ DELETE

عندما ينجح الطلب DELETE، يكون الرد الصحيح هو 204 لا يوجد محتوى — وليس 200 مع جسم فارغ، ولا 200 مع {"success": true}.

204 هو الإشارة المحددة التي تعني "تم النجاح وليست هناك جسم استجابة". 200 مع جسم فارغ منطقيًا صحيح، لكنه مبهم — لا يعرف العميل ما إذا كان الجسد كان مقصودًا وانطفأ، أو إذا كانت الانتهاء مقصودة. 204 يزيل هذا التباعد.

يُطبّق نفس المنطق على PUT وPATCH عندما لا تُرجع المورد المُحدث. إذا عادت API المورد بعد PATCH، استخدم 200. إذا لم تُرجع، استخدم 204. لا تُرجع 200 مع جسم فارغ {} أو null — هذا هو 204 يرتدي ملابسًا.

ملاحظة واحدة: 204 لا يجب أن يحتوي على جسم رسالة وفقًا لـ RFC 9110. إذا عدت إلى 204 وسجّلت جسمًا غير مقصود (تُسمح لك بعض الأطر)، فسيتعامل بعض متصفحات HTTP بشكل جيد، وبعضها لا. احذف الجسد في معالج الاستجابة، وليس فقط في الهدف.

مراجع سريع: الكود الذي يُسبب الأذى وسببه

شفرة	معنى	الخطأ الشائع	الحل
301	توجيه دائم	استخدام أثناء الاختبار — الآن يُحتفظ به بشكل دائم	استخدم 302 حتى تُثبت التوجيه الدائم
302	توجيه مؤقت	POST يُخفض إلى GET عند الاتجاه	استخدم 307 إذا كان الاتجاه يجب الحفاظ عليه
307	توجيه مؤقت (مُحمي من الطريقة)	مُضلل مع 302	استخدم عندما تُوجّه POST/PUT/PATCH مؤقتًا
308	توجيه دائم (مُحمي من الطريقة)	مُستبعد بدلًا من 301 بسبب العادة	استخدم بدلًا من 301 عندما يكون الاتجاه مهمًا
400	طلب غير صالح (خطأ في التحليل)	يُستخدم للاختبارات التحقق أيضًا	استخدم 422 للإخفاءات التي تفشل في التحقق من المعنى
401	غير مُصادق عليه	يُعاد إلى عندما يكون المستخدم يفتقر للإذن (يجب أن يكون 403)	أعد 401 فقط عندما تكون المعرفات مفقودة أو انتهت
403	حَرَام	يُعاد بدلًا من 404 للنطاقات الحساسة من حيث الأمان	أعد النظر في 404 عندما يهم إخفاء وجود النقطة
422	مُستحيل معالجة	مُدمج في 400	استخدم للاختبارات التي تفشل في التحقق من المعنى حيث كان الجسد قابلًا للتحليل
429	مُقيّد بالسرعة	مفقود رأسية Retry-After	أضف دائمًا رأسية Retry-After + X-RateLimit-*
503	غير متاح	مُضلل مع 504	استخدم عندما لا يستطيع الخادم المعالجة الطلب
504	مُتأخر في البوابة	مُضلل مع 503	استكشف الخدمة العليا، وليس البوابة
204	مُعدّل بدون محتوى	عند عرض 200 مع جسم فارغ	استخدم 204 لنجاح DELETE/PUT/PATCH بدون جسم استجابة

إذا كنت بحاجة إلى مراجعة سريعة لأي كود حالة أثناء التدقيق، IO Tools لديه مرجع لحالة HTTP الذي يغطي المدى الكامل مع وصف وملاحظات حول استخدام كل منها.

النمط وراء كل هذه الأمور

تُنشأ معظم هذه الأخطاء من نفس المكان: اعتبار الكودات حالة عامة ("4xx هو خطأ من جانب العميل، 5xx هو خطأ من جانب الخادم، مكتمل") بدلًا من اعتبارها كمُواصفات بروتوكول محددة. تُهم المُواصفات لأن المتصفحات — المتصفحات، أدوات HTTP، أدوات التخزين المؤقت، أدوات المراقبة — تُعتمد عليها. لن يُخزن متصفح 200 و204 بنفس الطريقة. لن يُعيد متصفح HTTP تجربة 400 و503 بطريقة متماثلة. لن يُخزن المتصفح 302 و301 بفترة انتهاء متماثلة.

استخدم الكود الصحيح. التكلفة صفر. الفائدة في التدقيق عندما ينهار شيء ما ليست صفرًا.

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