شرح رموز حالة HTTP

الفئات الخمس

• 1xx معلوماتية — استُلم الطلب والمعالجة مستمرة (100 Continue و101 Switching Protocols). نادراً ما يراها كود التطبيق.
• 2xx نجاح — فُهم الطلب وقُبل.
• 3xx إعادة توجيه — يجب على العميل فعل شيء آخر، عادةً اتباع عنوان URL جديد.
• 4xx خطأ من العميل — الطلب خاطئ: صياغة سيئة، أو مصادقة مفقودة، أو مورد غير موجود. لا ينبغي للعميل إعادة المحاولة دون تغيير.
• 5xx خطأ في الخادم — الطلب صالح لكن الخادم فشل. يمكن للعميل إعادة المحاولة، ويفضّل مع تراجع تدريجي.

جرّبها: مرجع رموز حالة HTTP

2xx: رموز النجاح

• 200 OK — النجاح القياسي؛ يحتوي الجسم على النتيجة.
• 201 Created — أُنشئ مورد (بعد POST أو PUT)؛ تشير ترويسة Location إليه.
• 202 Accepted — وُضع الطلب في قائمة الانتظار لمعالجة غير متزامنة؛ لم ينتهِ بعد.
• 204 No Content — نجاح بلا جسم (نموذجي لـ DELETE وبعض PUT/PATCH).
• 206 Partial Content — أُعيد نطاق من البايتات، ويُستخدم للتنزيلات القابلة للاستئناف والفيديو.

3xx: إعادة التوجيه

• 301 Moved Permanently — تغيّر العنوان نهائياً؛ تحدّث المتصفحات ومحركات البحث سجلاتها. يُستخدم لتغييرات العنوان القياسي.
• 302 Found — إعادة توجيه مؤقتة؛ يبقى العنوان الأصلي هو القياسي. قد تتغير الطريقة إلى GET.
• 303 See Other — بعد POST، اذهب ونفّذ GET على هذا العنوان الآخر (نمط post/redirect/get).
• 304 Not Modified — النسخة المخزّنة مؤقتاً ما زالت صالحة؛ لا يُرسل جسم. علامة على أن التخزين المؤقت يعمل.
• 307 / 308 — إعادة توجيه مؤقتة ودائمة تضمن الحفاظ على الطريقة والجسم. فضّل 308 على 301 في واجهات API.

جرّبها: فاحص إعادة التوجيه

4xx: أخطاء العميل

• 400 Bad Request — صياغة مشوّهة أو معاملات غير صالحة؛ خطأ التحقق العام.
• 401 Unauthorized — لا بيانات اعتماد صالحة. رغم الاسم فهو يعني «غير مصادَق». أرسل ترويسة WWW-Authenticate.
• 403 Forbidden — مصادَق لكنه غير مسموح له بهذا. إعادة المحاولة ببيانات الاعتماد نفسها لن تفيد.
• 404 Not Found — لا مورد في هذا العنوان (أو يفضّل الخادم عدم الإفصاح عن وجوده).
• 405 Method Not Allowed — العنوان موجود لكن ليس لهذه الطريقة (مثل DELETE على مورد للقراءة فقط). ضمّن ترويسة Allow.
• 409 Conflict — يتعارض الطلب مع الحالة الراهنة: مفتاح فريد مكرر، أو إصدار قديم، أو عملية سبق تنفيذها.
• 410 Gone — كان موجوداً وأُزيل عمداً ولن يعود.
• 415 Unsupported Media Type — ترويسة Content-Type خاطئة في جسم الطلب.
• 422 Unprocessable Entity — الصياغة سليمة لكن القيم تفشل في التحقق. شائع الاستخدام لأخطاء الحقول.
• 429 Too Many Requests — تجاوز حد المعدل؛ تخبرك ترويسة Retry-After بموعد المحاولة التالية.

جرّبها: محاكي رموز حالة API جرّبها: محلّل رموز حالة HTTP

5xx: أخطاء الخادم

• 500 Internal Server Error — استثناء غير معالَج. ليس أبداً الجواب الصحيح للمدخلات السيئة؛ فهو يعني أن التحقق مفقود.
• 501 Not Implemented — لا يدعم الخادم الطريقة إطلاقاً.
• 502 Bad Gateway — تلقّى الوكيل أو موزّع الحمل استجابة غير صالحة من الخادم الخلفي (انهار أو أرسل بيانات تالفة).
• 503 Service Unavailable — الخادم محمّل فوق طاقته أو في صيانة؛ مؤقت. أرسل Retry-After.
• 504 Gateway Timeout — انتظر الوكيل الخادم الخلفي ولم يجب في الوقت المحدد.

جرّبها: مولّد استجابات حالة HTTP وهمية

رموز يخلط الناس بينها

• 401 مقابل 403 — 401: من أنت؟ (سجّل الدخول). 403: أعرف من أنت، والجواب لا.
• 301 مقابل 302 مقابل 308 — دائم مقابل مؤقت؛ ويحافظ 308 أيضاً على POST كما هو.
• 400 مقابل 422 — 400 للطلبات غير القابلة للتحليل أو الخاطئة بنيوياً، و422 للطلبات سليمة البنية ذات القيم غير الصالحة. اختر اصطلاحاً واحداً والتزم به.
• 502 مقابل 503 مقابل 504 — الخادم الخلفي أعاد بيانات تالفة، مقابل الخادم غير متاح، مقابل الخادم الخلفي بطيء جداً.
• 404 مقابل 410 — غير معروف مقابل مُزال عمداً.

أي رمز يجب أن تعيده واجهتك؟

أعد الرمز الأكثر تحديداً الذي يصدق على الحالة، واستخدمه باتساق، وأرسل دائماً جسم خطأ بصيغة JSON برمز آلي ثابت ورسالة مفهومة. لا تغلّف الفشل أبداً في 200 — فالعملاء والمراقبة كلاهما يعتمد على سطر الحالة. حدّد المعدل بـ 429 وRetry-After، وتحقق بـ 400/422، وصادِق بـ 401، وفوّض بـ 403، واحتفظ بـ 500 للأخطاء البرمجية التي تنوي إصلاحها.

جرّبها: منشئ طلبات API جرّبها: محاكي رموز حالة API

الأسئلة الشائعة