مرجع HTTP Status

كل طلب HTTP في الإنترنت ينتهي برقم من ثلاث خانات: 200،404، 500. هذا الرقم ليس مجرد ردّ تقني، بل هو عقد بين الخادم والعميل يقول بدقّة: «هذا ما حدث، وهذا ما يجب أن تفعله الآن». استخدام كود خاطئ — مثلاً إعادة 200 OK لطلب فشل — يكسر الـ caches، يُربك الـ monitoring، ويخدع الـ retry logic في المتصفحات و SDKs.

المعيار RFC 9110 الصادر من IETF يُعرّف كل الأكواد القياسية ضمن خمس فئات. هذه المقالة تستعرضها بالعربية مع متى تستخدم كل كود، الفروقات الخفيّة بين أكواد متشابهة، وأخطاء شائعة في تصميم REST APIs تكلّفك ساعات debugging لاحقاً.

الخانة الأولى من الكود تحدّد فئته. 1xx معلوماتية (الطلب استُلم والمعالجة مستمرة)، 2xx نجاح (الطلب نُفّذ)، 3xx إعادة توجيه (يحتاج إجراء إضافي)، 4xx خطأ من العميل (الطلب نفسه فيه مشكلة)، 5xx خطأ من الخادم (الطلب صالح لكن الخادم فشل).

هذا التقسيم ليس تجميلياً: المتصفحات و reverse proxies و CDNs تتعامل مع كل فئة بشكل مختلف. 5xx مثلاً تُحفَّز retry تلقائي في كثير من العملاء، بينما 4xx لا تُعاد لأنّ المشكلة في الطلب نفسه. Cloudflare يخزّن 200 و 301 لفترات طويلة بشكل افتراضي لكنه لا يخزّن 500 أبداً.

200 OK مقابل 201 Created مقابل 204 No Content

الفرق بين الثلاثة دقيق وحاسم. 200 OK للطلب الناجح الذي يُعيد بيانات (الغالبية العظمى لـ GET). 201 Createdمخصّص لـ POST الذي ينشئ مورداً جديداً، ويجب أن يُعاد معه Location header يحتوي URL المورد الجديد. أمّا 204 No Content فللعمليات التي نجحت ولا تحتاج إعادة أي بيانات: DELETE ناجح، PUT بدون response body، أو PATCH صامت.

خطأ شائع: إعادة 200 مع جسم فارغ بدل 204. هذا يكسر بعض الـ HTTP clients التي تحاول parse الجسم وتفشل في null. القاعدة: إذا لم يكن لديك ما تعيده، استخدم 204.

202 Accepted للعمليات غير المتزامنة

عندما يستلم الـ API طلباً ويضعه في queue للمعالجة لاحقاً (إرسال إيميل، توليد تقرير ثقيل، training لـ ML model)، فالكود الصحيح هو 202 Accepted. أعِد معه عادةً URL أو ID للاستعلام عن حالة المهمة. هذا النمط أساسي في any API يتعامل مع long-running jobs.

هذه الأكواد الأربعة محور لخبط لا ينتهي. 301 Moved Permanentlyيقول إنّ المورد انتقل دائماً، والمتصفحات و SEO engines تخزّن الـ redirect وتحدّث الـ bookmarks. 302 Found يقول إنّها نقلة مؤقّتة — لا تخزّن.

المشكلة التاريخية: 301 و 302 لا يضمنان الحفاظ على HTTP method. متصفح كثيراً ما يُحوّل POST إلى GET بعدهما. لذا أضاف معيار HTTP الحديث 307 Temporary Redirectو 308 Permanent Redirect اللذين يحافظان على الـ method الأصلية بشكل صارم. القاعدة الحديثة: استخدم 308 للنقل الدائم في APIs، و 307 للنقل المؤقّت، واترك 301 و 302 لصفحات الويب التقليدية.

أمّا 304 Not Modified فقصة منفصلة: يُستخدم في conditional requests مع If-None-Match أو If-Modified-Since. الخادم يقول للعميل: «ما عندي جديد، استعمل النسخة المخزّنة عندك». توفير ضخم للـ bandwidth وللـ database queries.

401 Unauthorized مقابل 403 Forbidden

الفرق الأشهر في عالم HTTP. 401 يقول «أنت غير مُصادَق — لا أعرف من أنت»: التوكن مفقود، منتهٍ، أو غير صالح. الحلّ من جهة العميل: أعِد توجيهه لشاشة الدخول. أمّا 403 فيقول «أعرف من أنت لكنك لا تملك الصلاحية لهذا الإجراء»: المستخدم مسجَّل دخول لكن دوره (role) لا يسمح. الحلّ ليس إعادة دخول، بل عرض رسالة «ليس لديك صلاحية».

404 Not Found مقابل 410 Gone

404 يعني المورد غير موجود — قد يكون لم يوجد أصلاً، قد يعود يوماً. 410 Gone يقول صراحةً: «كان موجوداً ولن يعود». الفرق مهمّ لـ SEO: محرّكات البحث تزيل URLs التي تعطي 410 فوراً من الـ index، بينما تترك URLs الـ 404 لفترة أطول قبل إزالتها.

409 Conflict و 422 Unprocessable Entity

409 للحالات التي يتعارض فيها الطلب مع حالة المورد الحالية: تسجيل إيميل موجود، تحديث متزامن لنفس السجل، optimistic concurrency control يفشل. 422 — رغم أنّه ظهر أصلاً في WebDAV — تبنّاه Laravel و Rails و كثير من frameworks الحديثة لـ validation errors: الـ JSON صحيح بنيوياً لكن قيمه غير مقبولة (إيميل غير صالح، رقم خارج النطاق، حقل مطلوب فارغ).

429 Too Many Requests و دور Retry-After

عند تجاوز rate limit، أعِد 429 مع Retry-After header يحدّد بالثواني متى يمكن المحاولة مجدداً. عملاء HTTP الذكية (مثل axios-retry) تحترم هذا الـ header وتُؤخّر تلقائياً. بدونه، العميل قد يبدأ retry storm يفاقم المشكلة.

500 Internal Server Error هو الكود العام: شيء ما انكسر في الخادم ولا تعرف ماذا بالضبط. unhandled exception، null pointer، database connection lost. القاعدة الأمنية: سجّل stack trace كاملاً في logs الخادم، ولا تكشفه أبداً في الـ response — يكفي رسالة عامة "Something went wrong".

الأكواد الثلاثة التي تخلط بينها فرق-DevOps: 502 Bad Gatewayيعني reverse proxy (Nginx, Cloudflare, AWS ALB) استلم رداً غير صالح من الـ upstream — عادةً الـ backend مات أو رجع HTTP مكسور. 503 Service Unavailable يعني الخدمة غير متاحة مؤقّتاً عن قصد: صيانة، إعادة تشغيل، overload محسوس. أعِد Retry-After ليعرف العميل متى يحاول. 504 Gateway Timeout يعني الـ proxy انتظر الـ backend وانتهت المهلة بدون ردّ.

هذه الأكواد الثلاثة تأتي تقريباً دائماً من الـ infrastructure (Nginx، CDN، Load Balancer)، لا من كود تطبيقك. لو رأيتها في logs الـ proxy فابدأ التحقيق من upstream healthcheck.

القاعدة الذهبية في REST: اجعل الكود يصف ما حدث بدقّة، لا ما تشعر به. لو فشل validation فهو 422، ليس 400. لو المستخدم غير مسجَّل فهو 401، ليس 403. لو الطلب نجح بدون بيانات للإرجاع فهو 204، ليس 200 بجسم فارغ.

مثال على CRUD endpoint كامل: POST /users ينشئ مستخدماً → 201 + Location. GET /users/42→ 200 أو 404 إن لم يوجد. PUT /users/42ناجح بدون body → 204. DELETE /users/42→ 204. أمّا لو حاولت تسجيل إيميل مكرّر فـ 409، ولو أرسلت إيميل غير صالح فـ 422.

المتصفحات و CDNs تخزّن استجابات بناءً على الكود. الافتراضي: 200، 203، 204، 206، 300، 301، 404، 405، 410، 414، 501 قابلة للتخزين (وفق RFC 9111). البقية لا تُخزَّن افتراضياً.

من جهة الـ monitoring: أي نظام تنبيه جيد يفصل بين 4xxو 5xx. 4xx غالباً bug في العميل أو سلوك مشروع (مستخدم يحاول الوصول لشيء غير موجود). 5xxتنبيه مباشر لفريق المنصة — كل 500 ينبغي أن يُسجَّل مع كامل الـ context. أدوات مثل Sentry و Datadog تتعامل مع هذين النوعين بشكل مختلف تماماً في الـ alerting rules.

أكواد HTTP ليست تفاصيل ثانوية يمكن تجاهلها. كل كود تختاره يُملي سلوك المتصفحات، الـ CDNs، الـ retry logic، و dashboards الـ monitoring. اختيار 200 بدل 201قد يبدو تافهاً لكنّه يكسر معايير REST. اختيار 500بدل 503 يحرم نظامك من الـ retry-after الذكي.

ابدأ بحفظ الـ 15 كوداً الأكثر استخداماً (200, 201, 204, 301, 302, 304, 400, 401, 403, 404, 409, 422, 429, 500, 503)، وعُد لهذه المقالة عند تصميم أي endpoint جديد. المرجع التفاعلي أعلاه يخدمك كـ cheat sheet دائم.

في REST التقليديّ، الأكواد هي طبقة العقد بينك وبين العميل. لكن مع انتشار GraphQL و gRPC، فهم متى تستعمل أيّاً منها يحدّد ما إذا كان فريقك يبني API احترافيّاً أم مجرّد wrapper فوق قاعدة بيانات. القاعدة العمليّة:

• REST — اعتمد كامل سلّم الأكواد. POSTناجح ينشئ كياناً → 201 Created مع Locationheader. تحديث جزئي → 200 أو 204. خطأ تحقّق (validation) → 422 Unprocessable Entity مع جسم يُفصّل الحقول الفاشلة.
• GraphQL — يعيد دائماً 200 OK حتّى عند الأخطاء؛ الخطأ في حقل errors من الجسم. لكن لو رفض الـ gateway الطلب كاملاً (مثلاً حدّ تعقيد التعليمات البرمجيّة)، أعد 400 أو 429 كالمعتاد.
• gRPC — يستخدم أكواده الخاصّة (UNAVAILABLE, DEADLINE_EXCEEDED) لكنّ مدخل HTTP/2 يَترجمها لـ 503عند الإتاحة و 504 عند انتهاء المهلة. أدوات observability حديثة (OpenTelemetry, Datadog APM) تربط كود gRPC بكود HTTP لتسهيل الـ alerting.

توصية للفِرق السعوديّة التي تَبني على Spring Boot أو NestJS أو FastAPI: عرّف enum مركزيّ للأكواد المستعملة في مشروعك (لا تتجاوز عادة 20 كوداً)، و امنع الاستعمال الحرّ. هكذا تَحصل على تَلميحات IDE، unit tests يَفحص الكود الصحيح، و توثيق OpenAPI متّسق. Stripe و GitHub يَنشران علناً قائمة أكوادهما — اقرأها مرّة و اقتدِ بها.