كيف تصحّح أخطاء REST API: CORS و401 و403 و404 و415 وانتهاء المهلة
في هذه الصفحة 9 قسم
الإجابة المختصرة: أعد إنتاج الطلب الفاشل خارج تطبيقك، واقرأ رمز الحالة وجسم الاستجابة قبل أي شيء آخر، ثم غيّر شيئًا واحدًا في كل مرة. تقع معظم أخطاء API في بضعة أنماط، ورمز الحالة يخبرك بأيها. وإذا قال المتصفح «blocked by CORS policy» بينما ينجح الطلب نفسه في عميل API، فالمشكلة في ترويسات CORS على الخادم، لا في طلبك.
يستعرض هذا الدليل الأخطاء التي يواجهها المطورون أكثر عند دمج واجهة API، وما يعنيه كل منها فعلًا، وكيف تتأكد من السبب في دقائق من داخل VS Code.
يضيف تطبيقك طبقات: مكتبة HTTP، ومعترضات، ووكيل، والمتصفح. أزلها أولًا.
- في المتصفح، افتح DevTools ← Network، وانقر بزر الفأرة الأيمن على الطلب الفاشل واختر Copy → Copy as cURL.
- في VS Code، افتح عميل REST API في DevSnip Pro والصق أمر cURL في شريط العنوان. تُستورد الطريقة والترويسات والجسم.
- أرسله. يمكنك الآن تغيير ترويسة واحدة في كل مرة ورؤية الأثر فورًا.
إذا نجح الطلب هنا وفشل في المتصفح، فانتقل إلى قسم 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 Entity | JSON صالح، لكنه فشل في التحقق | قائمة أخطاء الحقول في جسم الاستجابة |
429 Too Many Requests | تجاوزت حد المعدل | ترويسة Retry-After |
5xx | فشل الخادم | سجلات الخادم؛ وهل تنجح مدخلات مختلفة |
- هل الترويسة موجودة أصلًا؟ تُسقط بعض عملاء HTTP ترويسة
Authorizationعند تتبّع إعادة توجيه إلى مضيف آخر. افحص الطلب الذي أُرسل فعلًا، لا الشيفرة التي تبنيه. - هل الصيغة صحيحة؟ تتوقع معظم الواجهات
Authorization: Bearer <token>بمسافة واحدة بالضبط، وكلمةBearerمرة واحدة. وتكرارBearer Bearer …خطأ شائع حين يُخزَّن الرمز مع بادئته. - هل انتهت صلاحية الرمز؟ الصق JWT في JWT Decoder & Signer في DevSnip Pro: يعرض الترويسة والمطالبات ويفحص
exp. وقارن أيضًاaud(الجمهور) وiss(المُصدِر) بما تتوقعه الواجهة. يعمل فك الترميز محليًا، فلا يذهب الرمز الحقيقي إلى أي موقع ويب.
يعرف الخادم من أنت، لكن رمزك أو مفتاحك يفتقر إلى صلاحية هذه العملية. انظر إلى النطاقات أو الأدوار في مطالبات الرمز، وصلاحيات مفتاح API، وما إذا كان المورد يخص حسابًا أو مستأجرًا آخر. ولن تفيد إعادة الطلب نفسه برمز جديد ما لم يكن للرمز الجديد صلاحيات أكثر.
وتُرجع بعض الخوادم أيضًا 403 حين يحظر جدار حماية أو WAF الطلب (مثلًا عند غياب User-Agent). وفي هذه الحالة يبدو جسم الاستجابة غالبًا كصفحة خطأ HTML لا كـ JSON.
قارن عنوان URL حرفًا حرفًا بوثائق الواجهة:
- العنوان الأساسي وإصدار الواجهة (
/مقابلv1/ /).v2/ - الشرطة المائلة الأخيرة:
/وusers /مساران مختلفان في كثير من الخوادم.users/ - معاملات المسار التي لم تُستبدل، مثل
/أوusers/ undefined /.users/ {id}
استخدام متغيرات البيئة مثل {{baseUrl}} للمضيف، بدلًا من كتابته في كل طلب، يزيل فئة كاملة من هذه الأخطاء. وإذا كان المسار صحيحًا وحصلت على 405، فالمسار موجود لكن ليس لتلك الطريقة؛ وتذكر ترويسة الاستجابة Allow الطرق التي يقبلها.
يحتاج جسم JSON إلى Content-Type: application/. ومن دونها لا تحلّل كثير من أطر العمل الجسم أصلًا، فيراه المعالج فارغًا. ويظهر ذلك كـ 415، أو كـ 400 يشكو من غياب حقول مطلوبة رغم أنك أرسلتها.
POST /v1/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer <token>
{"name": "Ada", "role": "admin"}وإذا كان الخادم يريد بيانات نموذج بدلًا من ذلك، فأرسل application/ (وهو المعتاد في نقاط نهاية رموز OAuth). وللتحقق من جسم JSON مقابل مخطط الواجهة قبل إرساله، استخدم JSON Schema Validator في DevSnip Pro: يعرض كل مخالفة مع مسارها.
لا تفرض سوى المتصفحات سياسة 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.القيمة الافتراضية (30 ثانية)، وتتجاوزها المهلة الخاصة بالطلب، ويوقف Cancel الطلب مبكرًا.apiTimeout
بمجرد أن ينجح الطلب في عميل API، ولّد الاستدعاء نفسه بـ JavaScript (fetch أو Axios) أو Python أو Go أو Java أو C# وقارنه بشيفرتك. يكون الفرق عادةً في ترويسة، أو ترميز الجسم، أو عنوان URL.