Frontend Academy · درس

معالجة الأخطاء: رموز حالة HTTP

اربط رموز حالة HTTP برسائل موجّهة إلى المستخدم، وميّز بين أخطاء الشبكة وأخطاء الخادم، ونفّذ منطق إعادة المحاولة

معالجة الأخطاء: رموز حالة HTTP درس مجاني في Frontend Academy على CoddyKit. هذا هو الدرس 3 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Frontend Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Frontend Academy 4 دروس في المجموع.

فئات رموز حالة HTTP

تُجمَّع رموز الحالة حسب الرقم الأول: 2xx نجاح، و3xx إعادة توجيه، و4xx خطأ من العميل (المشكلة من جانبكم)، و5xx خطأ من الخادم (المشكلة من جانبهم).

رموز 2xx الشائعة

200 OK: نجاح مع محتوى. 201 Created: تم إنشاء المورد (وغالبًا ما يُعاد المورد الجديد). 204 No Content: نجاح من دون محتوى (في DELETE، وأحيانًا PUT).

رموز 4xx الشائعة

400 Bad Request: إدخال مشوّه. 401 Unauthorized: بيانات المصادقة مفقودة أو غير صالحة. 403 Forbidden: تمت المصادقة، لكن الوصول غير مسموح. 404 Not Found: المورد غير موجود. 409 Conflict: تعارض في الحالة (مثل بريد إلكتروني مكرر). 422 Unprocessable Entity: فشل التحقق.

رموز 5xx الشائعة

500 Internal Server Error: خطأ عام في الخادم. 502 Bad Gateway: فشلت خدمة upstream. 503 Service Unavailable: الخادم مثقل أو متوقف. 504 Gateway Timeout: لم تستجب خدمة upstream في الوقت المحدد.

تحويل الرموز إلى رسائل للمستخدم

حوّلوا رموز الحالة إلى رسائل مفيدة في واجهة المستخدم — ولا تعرضوا للمستخدم مطلقًا الرسالة 'Error 500'.

function userMessage(status) {
  if (status === 401) return 'Please sign in to continue.';
  if (status === 403) return "You don't have permission for that.";
  if (status === 404) return 'Not found.';
  if (status === 409) return 'Already exists.';
  if (status === 422) return 'Please check the form for errors.';
  if (status >= 500) return 'Something went wrong. Try again in a moment.';
  return 'Something unexpected happened.';
}

أخطاء الشبكة مقابل أخطاء الخادم

يختلف فشل fetch (بسبب عدم الاتصال أو فشل DNS أو CORS) عن استجابة خطأ من الخادم. تُلقي أخطاء الشبكة استثناءً؛ أما أخطاء الخادم فتعيد كائن Response بحالة >= 400.

try {
  const res = await fetch('/api/users');
  if (!res.ok) {
    // Server replied but with error status
    throw new Error(`Server error ${res.status}`);
  }
  return res.json();
} catch (err) {
  if (err instanceof TypeError) {
    // Network failure — fetch couldn't reach server
    throw new Error('Network error. Check your connection.');
  }
  throw err;
}

منطق إعادة المحاولة لأخطاء 5xx وأخطاء الشبكة

غالبًا ما تكون أخطاء الخادم وفشل الشبكة مؤقتة. أعيدوا المحاولة مع تأخير أُسّي متزايد.

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const res = await fetch(url, options);
      if (res.ok || (res.status >= 400 && res.status < 500)) return res;
      // 5xx — retryable
    } catch (err) {
      if (attempt === maxRetries - 1) throw err;
    }
    await new Promise(r => setTimeout(r, 2 ** attempt * 1000)); // 1s, 2s, 4s
  }
}

لا تعيدوا محاولة 4xx

أخطاء 4xx ناتجة عن جانبكم — وإعادة المحاولة لن تساعد. أعيدوا المحاولة فقط عند أخطاء 5xx وفشل الشبكة. الاستثناء هو 429 (Too Many Requests)، الذي يتضمن غالبًا ترويسة Retry-After.

قراءة ترويسة Retry-After

قد تتضمن الخوادم Retry-After مع 429 و503 — انتظروا ذلك العدد من الثواني قبل إعادة المحاولة.

const res = await fetch('/api/limited');
if (res.status === 429) {
  const after = parseInt(res.headers.get('Retry-After') || '5', 10);
  await new Promise(r => setTimeout(r, after * 1000));
  return fetch('/api/limited');
}

عرض أخطاء التحقق

تتضمن استجابات 422 عادةً نص JSON يسرد أخطاء الحقول. اعرضوها بجانب حقل الإدخال ذي الصلة في النموذج.

// Server response for 422:
// { errors: { email: 'Already taken', password: 'Too short' } }

if (res.status === 422) {
  const { errors } = await res.json();
  Object.entries(errors).forEach(([field, msg]) => {
    setFieldError(field, msg);
  });
}

القياس عن بُعد: تسجيل الأخطاء في خدمة

أرسلوا الأخطاء إلى Sentry أو Datadog أو LogRocket كي تتمكنوا من رؤيتها في بيئة الإنتاج. أدرجوا عنوان URL للطلب، والطريقة، والحالة، والنص المنقّى (من دون أسرار).

إتاحة إجراء عملي للتعافي

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

تحقق سريع

تعيد واجهة API استجابة 422 Unprocessable Entity. ما الذي يعنيه ذلك عادةً؟

مراجعة: معالجة أخطاء HTTP

2xx نجاح، و3xx إعادة توجيه، و4xx خطأ من العميل، و5xx خطأ من الخادم. حوّلوا الرموز إلى رسائل سهلة الفهم للمستخدم. ميّزوا بين أخطاء الشبكة (TypeError من fetch) وأخطاء الخادم (res.ok بقيمة false). أعيدوا محاولة أخطاء 5xx وفشل الشبكة مع تأخير أُسّي متزايد؛ ولا تعيدوا محاولة 4xx مطلقًا (باستثناء 429 مع Retry-After). اعرضوا أخطاء الحقول في استجابات 422. سجّلوا الأخطاء في خدمة مثل Sentry.

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

هل درس «معالجة الأخطاء: رموز حالة HTTP» مجاني؟

نعم — نص درس «معالجة الأخطاء: رموز حالة HTTP» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Frontend Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Frontend Academy 4 دروس في المجموع.

ماذا ستتعلم في «معالجة الأخطاء: رموز حالة HTTP»؟

اربط رموز حالة HTTP برسائل موجّهة إلى المستخدم، وميّز بين أخطاء الشبكة وأخطاء الخادم، ونفّذ منطق إعادة المحاولة تتمرن على Frontend Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Frontend Academy؟

لا تُشترط خبرة سابقة. Frontend Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 3 من أصل 4.

كم من الوقت يستغرق درس «معالجة الأخطاء: رموز حالة HTTP»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Frontend Academy هذا؟

نعم. كل درس في Frontend Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى Frontend Academy