أكواد حالة HTTP هي الأرقام المكوّنة من ثلاث خانات التي يُرجِعها الخادم في بداية كل استجابة لتلخيص ما جرى. هذه الأكواد هي الطريقة التي تعتمد عليها المتصفحات والعملاء والوسطاء وشبكات CDN لتقرر هل تُخزِّن الاستجابة في الكاش، أم تُعيد التوجيه، أم تُعيد المحاولة، أم تُظهر خطأً للمستخدم.
كل كود حالة ينتمي إلى واحدة من خمس فئات بناءً على أول خانة فيه: 1xx معلوماتي، 2xx نجاح، 3xx إعادة توجيه، 4xx خطأ من العميل، 5xx خطأ من الخادم. بمجرد أن تعرف الفئة، تستطيع غالبًا تخمين المعنى العام حتى قبل أن تبحث عن الكود تحديدًا.
معظم التطبيقات تستخدم مجموعة محدودة فقط (200, 201, 204, 301, 302, 304, 400, 401, 403, 404, 409, 422, 429, 500, 502, 503). إتقان معنى كل واحد منها - والتمييز بين 401 Unauthorized و403 Forbidden، أو بين 301 Moved Permanently و302 Found - هو ما يجعلك مطوِّر باك-إند أو واجهات API أقوى.
ماذا ستتعلّم أثناء استخدام هذا المرجع
أول خانة في الكود تُخبرك دائمًا بالفئة: 1xx معلوماتي، 2xx نجاح، 3xx إعادة توجيه، 4xx خطأ من العميل، 5xx خطأ من الخادم.
أكواد الحالة *جزء من العقد* الذي تُقدِّمه الـ API - يجب على العملاء أن يتفرّعوا بناءً عليها، لا أن يحلّلوا رسائل الخطأ من جسم الاستجابة.
4xx يعني أن العميل أخطأ في شيء (إدخال خاطئ، أو غياب توثيق، أو مورد غير موجود). أمّا 5xx فيعني أن الخادم فشل بغضّ النظر عمّا فعله العميل.
كيف تستخدم مرجع أكواد الحالة خطوة بخطوة
1
ابحث برقم الكود أو باسمه
اكتب رقمًا (404, 429) أو كلمة مفتاحية (auth, redirect, rate limit) وستتم تصفية الأكواد المطابقة فورًا أثناء الكتابة.
2
صفِّ النتائج حسب الفئة
استخدم أزرار الفئات (1xx, 2xx, 3xx, 4xx, 5xx) لتقليص القائمة عندما تتصفّح بدلًا من البحث عن كود محدد.
3
اقرأ الشرح بلغة بسيطة
كل عنصر يتضمّن متى يُرسَل الكود، والسلوك المعتاد من جانب العميل، والسبب الأكثر شيوعًا لظهوره.
4
قارِن بين الأكواد المتشابهة
استخدم روابط "انظر أيضًا" بين الأزواج المُربكة (401 مقابل 403, 301 مقابل 302) لتختار الأنسب لـ API الخاصة بك.
إعادة توجيه مؤقتة. المتصفحات تُعيد فحص الرابط الأصلي مع كل طلب؛ والإشارات المرجعية تظل مرتبطة بالرابط القديم.
استخدم 301 عندما تكون قد نقلت المورد فعلًا (تغيير علامة تجارية، إعادة هيكلة للروابط). واستخدم 302 لإعادات التوجيه قصيرة الأمد مثل اختبارات A/B، أو إعادة توجيه تسجيل الدخول، أو صفحات الصيانة.
الخادم يعرف من أنت، لكن ليس لديك الصلاحية للوصول إلى هذا المورد.
إذا كان إرسال بيانات اعتماد مختلفة قد يحلّ المشكلة، فأرجِع 401. أمّا إذا كانت بيانات الاعتماد لن تُجدي نفعًا (المورد ممنوع على هذا المستخدم بالأساس)، فأرجِع 403.
انتهت مهلة البوابة - وصل الوسيط إلى الخادم الخلفي لكنه لم يحصل على ردّ في الوقت المناسب.
الأربعة جميعها أخطاء خادم، لكنها تروي قصصًا مختلفة تمامًا للمصحِّح. 500 يدلّ على تطبيقك؛ و502 و504 يشيران إلى مسار الشبكة؛ و503 يشير إلى مشكلة في السعة.
أخطاء شائعة في استخدام أكواد حالة HTTP
إرجاع 200 OK مع {"error": "..."} في جسم الاستجابة. أكواد الحالة جزء من العقد - استخدم الكود الصحيح (400, 404, 500) حتى يتمكّن العملاء من التفرّع بناءً عليه.
استخدام 401 لأخطاء الصلاحيات. الكود 401 مخصَّص للتوثيق؛ أمّا رفض الصلاحيات فهو 403.
استخدام 200 للموارد المُنشَأة حديثًا بدلًا من 201 مع ترويسة Location.
أسئلة شائعة عن أكواد حالة HTTP
ماذا يعني HTTP 404؟
404 Not Found يعني أن الخادم فهم الطلب، لكن المورد عند ذلك الرابط غير موجود. غالبًا يكون السبب أن المسار خاطئ، أو أن المورد قد حُذف، أو أن الرابط كُتب بصورة غير صحيحة.
ما الفرق بين 401 و403؟
401 Unauthorized يعني أنك غير موثَّق - الخادم لا يعرف من أنت. أمّا 403 Forbidden فيعني أنك موثَّق لكن ليس لديك صلاحية للوصول إلى المورد. إرسال بيانات اعتماد مختلفة قد يحلّ مشكلة 401، لكنه لن يحلّ مشكلة 403.
ما الفرق بين 301 و302؟
301 Moved Permanently هو إعادة توجيه دائمة - المتصفحات ومحركات البحث تُحدِّث سجلاتها بناءً عليها. أمّا 302 Found فهو إعادة توجيه مؤقتة - حيث يستمر العملاء في زيارة الرابط الأصلي. استخدم 301 للنقل الدائم، و302 للتحويلات المؤقتة.
ماذا يعني HTTP 500؟
500 Internal Server Error هو خطأ عام من جهة الخادم، يُطلَق عادةً عندما يصعد استثناء غير مُعالَج إلى الأعلى. العميل لم يفعل شيئًا خاطئًا - الخادم هو الذي فشل في معالجة طلب صحيح.
هل يجب أن أستخدم دائمًا كود حالة محدَّد؟
نعم. استخدام 200 OK العام للفشل، أو 500 لكل المشاكل، يجعل الـ API أصعب في الاستخدام. اختر الكود الأكثر تخصيصًا الذي يُناسب الحالة - فالعملاء والوسطاء وأنظمة المراقبة ومنطق إعادة المحاولة كلهم يتفرّعون بناءً على كود الحالة.
ماذا يعني HTTP 429؟
429 Too Many Requests يُرسَل عندما يتجاوز العميل حدّ المعدل المسموح به. يجب أن تتضمّن الاستجابة ترويسة Retry-After تُخبر العميل متى يكون من الآمن المحاولة من جديد.
