كيف تصحّح أخطاء REST API: ‏CORS و401 و403 و404 و415 وانتهاء المهلة

بقلم Sayaib Sarkarآخر تحديث قراءة في 6 دقيقة

في هذه الصفحة 9 قسم

الإجابة المختصرة: أعد إنتاج الطلب الفاشل خارج تطبيقك، واقرأ رمز الحالة وجسم الاستجابة قبل أي شيء آخر، ثم غيّر شيئًا واحدًا في كل مرة. تقع معظم أخطاء API في بضعة أنماط، ورمز الحالة يخبرك بأيها. وإذا قال المتصفح «blocked by CORS policy» بينما ينجح الطلب نفسه في عميل API، فالمشكلة في ترويسات CORS على الخادم، لا في طلبك.

يستعرض هذا الدليل الأخطاء التي يواجهها المطورون أكثر عند دمج واجهة API، وما يعنيه كل منها فعلًا، وكيف تتأكد من السبب في دقائق من داخل VS Code.

الخطوة 1: أعد إنتاج الطلب خارج تطبيقك

يضيف تطبيقك طبقات: مكتبة HTTP، ومعترضات، ووكيل، والمتصفح. أزلها أولًا.

  1. في المتصفح، افتح DevTools ← Network، وانقر بزر الفأرة الأيمن على الطلب الفاشل واختر Copy → Copy as cURL.
  2. في VS Code، افتح عميل REST API في DevSnip Pro والصق أمر cURL في شريط العنوان. تُستورد الطريقة والترويسات والجسم.
  3. أرسله. يمكنك الآن تغيير ترويسة واحدة في كل مرة ورؤية الأثر فورًا.

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

اقرأ رمز الحالة والجسم

قبل تغيير الشيفرة، اقرأ ما أرسله الخادم. تشرح كثير من الواجهات المشكلة في جسم الاستجابة، مثل {"error": "invalid_token", "error_description": "The access token expired"}.

الحالةما تعنيه عادةًافحص أولًا
400 Bad Requestالجسم أو المعاملات غير صالحةجسم الاستجابة؛ والحقول المطلوبة؛ وصيغة JSON
401 Unauthorizedلم تُرسل بيانات اعتماد صالحةترويسة Authorization؛ وانتهاء صلاحية الرمز
403 Forbiddenبيانات الاعتماد صالحة لكنها غير مسموح لها بذلكنطاقات الرمز أو أدواره؛ وصلاحيات مفتاح API
404 Not Foundعنوان URL خاطئ، أو المورد غير موجودالعنوان الأساسي، والمسار، والشرطة المائلة الأخيرة، وإصدار API
405 Method Not Allowedالعنوان صحيح، والطريقة خاطئةGET مقابل POST؛ وترويسة الاستجابة Allow
415 Unsupported Media Typeلا يستطيع الخادم قراءة صيغة الجسمترويسة Content-Type
422 Unprocessable EntityJSON صالح، لكنه فشل في التحقققائمة أخطاء الحقول في جسم الاستجابة
429 Too Many Requestsتجاوزت حد المعدلترويسة Retry-After
5xxفشل الخادمسجلات الخادم؛ وهل تنجح مدخلات مختلفة

‏401 Unauthorized: بيانات الاعتماد لم تصل أو غير صالحة

  • هل الترويسة موجودة أصلًا؟ تُسقط بعض عملاء HTTP ترويسة Authorization عند تتبّع إعادة توجيه إلى مضيف آخر. افحص الطلب الذي أُرسل فعلًا، لا الشيفرة التي تبنيه.
  • هل الصيغة صحيحة؟ تتوقع معظم الواجهات Authorization: Bearer <token> بمسافة واحدة بالضبط، وكلمة Bearer مرة واحدة. وتكرار Bearer Bearer … خطأ شائع حين يُخزَّن الرمز مع بادئته.
  • هل انتهت صلاحية الرمز؟ الصق JWT في JWT Decoder & Signer في DevSnip Pro: يعرض الترويسة والمطالبات ويفحص exp. وقارن أيضًا aud (الجمهور) وiss (المُصدِر) بما تتوقعه الواجهة. يعمل فك الترميز محليًا، فلا يذهب الرمز الحقيقي إلى أي موقع ويب.

‏403 Forbidden: هويتك صحيحة، لكن ما تفعله غير مسموح

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

وتُرجع بعض الخوادم أيضًا 403 حين يحظر جدار حماية أو WAF الطلب (مثلًا عند غياب User-Agent). وفي هذه الحالة يبدو جسم الاستجابة غالبًا كصفحة خطأ HTML لا كـ JSON.

‏404 Not Found و405 Method Not Allowed

قارن عنوان URL حرفًا حرفًا بوثائق الواجهة:

  • العنوان الأساسي وإصدار الواجهة (/v1/ مقابل /v2/).
  • الشرطة المائلة الأخيرة: /users و/users/ مساران مختلفان في كثير من الخوادم.
  • معاملات المسار التي لم تُستبدل، مثل /users/undefined أو /users/{id}.

استخدام متغيرات البيئة مثل {{baseUrl}} للمضيف، بدلًا من كتابته في كل طلب، يزيل فئة كاملة من هذه الأخطاء. وإذا كان المسار صحيحًا وحصلت على 405، فالمسار موجود لكن ليس لتلك الطريقة؛ وتذكر ترويسة الاستجابة Allow الطرق التي يقبلها.

‏415 و400: الجسم ليس ما يتوقعه الخادم

يحتاج جسم JSON إلى Content-Type: application/json. ومن دونها لا تحلّل كثير من أطر العمل الجسم أصلًا، فيراه المعالج فارغًا. ويظهر ذلك كـ 415، أو كـ 400 يشكو من غياب حقول مطلوبة رغم أنك أرسلتها.

HTTP
POST /v1/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer <token>

{"name": "Ada", "role": "admin"}

وإذا كان الخادم يريد بيانات نموذج بدلًا من ذلك، فأرسل application/x-www-form-urlencoded (وهو المعتاد في نقاط نهاية رموز OAuth). وللتحقق من جسم JSON مقابل مخطط الواجهة قبل إرساله، استخدم JSON Schema Validator في DevSnip Pro: يعرض كل مخالفة مع مسارها.

‏CORS: «blocked by CORS policy»

لا تفرض سوى المتصفحات سياسة CORS. أما curl وPostman وتطبيقات الجوال والاستدعاءات بين الخوادم فتتجاهلها، ولهذا قد ينجح الطلب في عميل API ويفشل في تطبيق الويب. والإصلاح دائمًا على الخادم: يجب أن يرسل ترويسات Access-Control-* الصحيحة لأصل صفحتك.

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

  • غياب ترويسة Access-Control-Allow-Origin، أو وجودها بأصل مختلف. فـ http://localhost:3000 وhttp://localhost:5173 أصلان مختلفان.
  • فشل طلب OPTIONS التمهيدي. تُطلق الطلبات ذات جسم JSON أو ترويسة Authorization طلبًا تمهيديًا. وإذا أجاب الخادم عنه بـ 401 أو 404 أو 405 (غالبًا لأن وسيط المصادقة يعمل قبل CORS)، يحظر المتصفح الطلب الحقيقي.
  • بيانات اعتماد مع حرف بدل. مع ملفات تعريف الارتباط (credentials: 'include')، يجب أن يُرجع الخادم الأصل الدقيق وAccess-Control-Allow-Credentials: true. ولا يُسمح بـ Access-Control-Allow-Origin: *.
  • أخطاء دون ترويسات CORS. إذا أرجع الخادم 500 دون ترويسات CORS، يبلّغ المتصفح عن خطأ CORS ويخفي الخطأ الحقيقي. أرجع ترويسات CORS في استجابات الخطأ أيضًا.

يوفر CORS Builder & Debugger في DevSnip Pro ثلاثة أوضاع لذلك: الصق خطأ وحدة التحكم لتحصل على السبب المرجّح والإصلاح، أو الصق ترويسات الاستجابة لفحصها كما يفعل المتصفح، أو ولّد إعدادًا صحيحًا لـ Express أو NestJS أو Next.js أو Fastify أو nginx أو FastAPI.

انتهاء المهلة والطلبات التي لا تنتهي أبدًا

  • تحقق من أن شيئًا يستمع أصلًا. يعرض Port & Network Toolkit في DevSnip Pro المنافذ المحلية الحرة: فإذا كان المنفذ الذي يجب أن تستخدمه واجهتك حرًا، فالخادم لا يعمل عليه.
  • الطلب إلى localhost من هاتف أو محاكٍ يذهب إلى الجهاز نفسه، لا إلى حاسوبك. استخدم عنوان جهازك على الشبكة المحلية، أو الاسم المستعار للمضيف في المحاكي.
  • قد تحتاج الاستجابات الكبيرة ونقاط النهاية البطيئة إلى مهلة أطول. في DevSnip Pro، يضبط devsnip.apiTimeout القيمة الافتراضية (30 ثانية)، وتتجاوزها المهلة الخاصة بالطلب، ويوقف Cancel الطلب مبكرًا.

ثم أصلحه في الشيفرة

بمجرد أن ينجح الطلب في عميل API، ولّد الاستدعاء نفسه بـ JavaScript ‏(fetch أو Axios) أو Python أو Go أو Java أو C#‎ وقارنه بشيفرتك. يكون الفرق عادةً في ترويسة، أو ترميز الجسم، أو عنوان URL.

جرّبه في محررك

مجاني، دون حساب، ويعمل محليًا. لـ VS Code 1.93 أو أحدث وبيئات JetBrains على Windows أو macOS أو Linux.

code --install-extension sayaib.hue-console