أكواد خطأ curl: المرجع الكامل

جدول مرجعي سريع

الخطأ 6: تعذر تحليل المضيف

ماذا يعني

تظهر الطرفية الخاصة بك curl: (6) Could not resolve host. لم يتمكن curl من تحليل اسم المضيف إلى عنوان IP — فشل بحث DNS قبل محاولة أي اتصال.

الأسباب

الأسباب الأكثر شيوعاً هي: خطأ مطبعي في اسم المضيف (على سبيل المثال، curl https://apiexample.com بدلاً من api.example.com)، مشكلات في خادم DNS (خادم DNS المهيأ لديك معطل أو لا يمكن الوصول إليه)، عدم وجود اتصال بالشبكة (Wi-Fi مفصول، VPN غير متصل)، أو أن النطاق غير موجود فعلياً.

كيفية الإصلاح

أولاً، تحقق من صحة الرابط (URL). ثم اختبر تحليل DNS مباشرة: nslookup api.example.com أو dig api.example.com. إذا فشل DNS، جرب خادم DNS مختلفاً: curl --dns-servers 8.8.8.8 https://api.example.com. تحقق من ملف /etc/resolv.conf أو إعدادات الشبكة. إذا كنت خلف VPN خاص بالشركة، فتأكد من أن DNS الداخلي يمكنه تحليل المضيف.

$ curl https://api.exmple.com/users

الخطأ 7: فشل الاتصال

ماذا يعني

تظهر الطرفية الخاصة بك curl: (7) Failed to connect to host port: Connection refused. قام curl بتحليل اسم المضيف ولكنه لم يتمكن من إنشاء اتصال TCP بالخادم — تم رفض الاتصال بشكل نشط أو انتهت المهلة على مستوى TCP.

الأسباب

تشمل الأسباب الشائعة: الخادم معطل أو لا يعمل، جدار حماية يحظر المنفذ (تحقق من جدران الحماية المحلية وجانب الخادم)، المنفذ خاطئ (على سبيل المثال، الخدمة تعمل على 8080 ولكنك تتصل بـ 443)، أو أن قائمة انتظار الاستماع (listen backlog) للخادم ممتلئة تحت ضغط عالٍ.

كيفية الإصلاح

تحقق من أن الخادم يعمل: ping api.example.com و telnet api.example.com 443. تحقق مما إذا كان المنفذ الصحيح مفتوحاً: nmap -p 443 api.example.com. قم بتعطيل جدار الحماية المحلي مؤقتاً للاختبار. إذا كنت تستخدم Docker، فتأكد من نشر منفذ الحاوية. جرب الوضع التفصيلي: curl -v https://api.example.com لمعرفة مكان فشل الاتصال بالضبط.

$ curl https://localhost:8080/api

الخطأ 22: أعاد HTTP خطأ

ماذا يعني

تظهر الطرفية الخاصة بك curl: (22) The requested URL returned error. أعاد الخادم كود حالة خطأ HTTP (4xx أو 5xx) وتم استدعاء curl مع -f أو --fail، مما يخبر curl بمعاملة أخطاء HTTP كإخفاقات.

الأسباب

يتم إطلاق الخطأ بواسطة أكواد حالة HTTP مثل 400 (Bad Request)، 401 (Unauthorized)، 403 (Forbidden)، 404 (Not Found)، أو 500 (Internal Server Error) — ولكن فقط عند استخدام --fail. بدون --fail، يخرج curl بالكود 0 حتى في حالة أخطاء HTTP. الأسباب الشائعة: رابط خاطئ، فقدان المصادقة، أذونات غير كافية، أو أخطاء في جانب الخادم.

كيفية الإصلاح

قم بتشغيل curl بدون --fail لرؤية جسم الاستجابة الكامل — غالباً ما يحتوي على رسالة الخطأ الفعلية. تحقق من كود حالة HTTP: curl -w "%{http_code}" -o /dev/null -s URL. بالنسبة لـ 401/403: تحقق من رمز المصادقة (auth token) أو مفتاح API. بالنسبة لـ 404: تحقق جيداً من مسار الرابط. بالنسبة لـ 500: المشكلة من جانب الخادم.

$ curl --fail https://api.example.com/nonexistent

الخطأ 28: انتهت مهلة العملية

ماذا يعني

تظهر الطرفية الخاصة بك curl: (28) Operation timed out أو curl: (28) Connection timed out. استغرقت العملية وقتاً أطول من الوقت المسموح به. هذا هو خطأ curl الأكثر شيوعاً — يمكن أن يحدث أثناء تحليل DNS، أو اتصال TCP، أو مصافحة SSL، أو نقل البيانات.

الأسباب

تشمل الأسباب النموذجية: خادم بطيء أو مثقل لا يستجيب في الوقت المناسب، ازدحام الشبكة أو فقدان الحزم، جدار حماية يسقط الحزم بصمت (لا يوجد رفض، فقط صمت)، قيم مهلة صارمة للغاية تم تعيينها باستخدام --connect-timeout أو --max-time، أو تكوين خاطئ للبروكسي يسبب تأخيرات.

كيفية الإصلاح

قم بزيادة المهلة: curl --connect-timeout 30 --max-time 120 URL. استخدم الوضع التفصيلي لمعرفة مكان التوقف: curl -v URL. اختبر زمن انتقال الشبكة: ping api.example.com و traceroute api.example.com. إذا كنت خلف بروكسي، جرب تجاوزه: curl --noproxy '*' URL. لنقل الملفات الكبيرة، فكر في استخدام --retry 3 مع --retry-delay 5.

$ curl --connect-timeout 5 https://slow-api.example.com/data

الخطأ 35: خطأ في اتصال SSL

ماذا يعني

تظهر الطرفية الخاصة بك curl: (35) SSL connect error. فشلت مصافحة SSL/TLS — لم يتمكن curl من إنشاء اتصال آمن مع الخادم.

الأسباب

الأسباب الشائعة: عدم تطابق إصدار TLS (يتطلب الخادم TLS 1.3 ولكن curl لديك يدعم فقط حتى TLS 1.2)، عدم توافق مجموعة التشفير (cipher suite)، تكوين خاطئ لـ SSL في الخادم (تقديم شهادة منتهية الصلاحية أثناء المصافحة، سلسلة غير مكتملة)، الخادم لا يدعم HTTPS فعلياً على المنفذ المحدد، أو بروكسي أو جدار حماية يعترض اتصال SSL (MITM).

كيفية الإصلاح

فرض إصدار TLS محدد: curl --tlsv1.2 URL أو curl --tlsv1.3 URL. تحقق مما يدعمه الخادم: openssl s_client -connect api.example.com:443. قم بتحديث curl و OpenSSL إلى أحدث الإصدارات. إذا كان الخادم يستخدم شهادة موقعة ذاتياً، فعادة ما يكون هذا هو الخطأ 60 بدلاً من ذلك — يشير الخطأ 35 عادةً إلى فشل المصافحة على مستوى البروتوكول.

$ curl https://legacy-server.example.com/api

الخطأ 56: فشل الاستلام — تمت إعادة تعيين الاتصال

ماذا يعني

تظهر الطرفية الخاصة بك curl: (56) Recv failure: Connection reset by peer. تم إنشاء الاتصال بنجاح، ولكن فشل استلام البيانات — أغلق الخادم الاتصال أو أعاد تعيينه بشكل غير متوقع أثناء النقل.

الأسباب

يحدث هذا غالباً عندما: يتعطل الخادم أو يعاد تشغيله في منتصف النقل، موازن تحميل أو بروكسي يسقط الاتصال (مهلة الخمول، الطلب كبير جداً)، جدار حماية ينهي الاتصالات طويلة الأمد، الخادم لديه مهلة بقاء (keep-alive) أقصر مما هو متوقع، أو هناك انقطاع في الشبكة بين العميل والخادم.

كيفية الإصلاح

حاول تنفيذ الطلب مرة أخرى — مشكلات الشبكة العابرة هي السبب الأكثر شيوعاً. استخدم الوضع التفصيلي: curl -v URL لرؤية نقطة الفشل بالضبط. إذا حدث الخطأ أثناء عمليات رفع كبيرة، جرب النقل المجزأ (chunked transfer): curl -H "Transfer-Encoding: chunked" URL. لعمليات Git التي تظهر RPC failed; curl 56، قم بزيادة المخزن المؤقت: git config http.postBuffer 524288000.

$ curl https://api.example.com/large-download

الخطأ 60: مشكلة في شهادة SSL

ماذا يعني

تظهر الطرفية الخاصة بك curl: (60) SSL certificate problem: unable to get local issuer certificate. لم يتمكن curl من التحقق من شهادة SSL الخاصة بالخادم مقابل حزمة CA (سلطة الشهادات) الخاصة به. اكتملت مصافحة TLS على مستوى البروتوكول، ولكن فشل التحقق من الشهادة.

الأسباب

الأسباب الأكثر شيوعاً: يستخدم الخادم شهادة موقعة ذاتياً، الشهادة منتهية الصلاحية، سلسلة الشهادات غير مكتملة (فقدان الشهادات الوسيطة)، حزمة CA الخاصة بـ curl قديمة (شائع في الأنظمة القديمة أو في حاويات Docker)، أو أن الاسم الشائع (Common Name) / SAN للشهادة لا يتطابق مع اسم المضيف المطلوب.

كيفية الإصلاح

قم بتحديث حزمة CA: curl --cacert /path/to/cacert.pem URL. قم بتنزيل حزمة محدثة من https://curl.se/ca/cacert.pem. للتشخيص: openssl s_client -connect api.example.com:443 -showcerts. بالنسبة للشهادات الموقعة ذاتياً في بيئة التطوير، استخدم curl -k URL (أبداً في بيئة الإنتاج — حيث يقوم بتعطيل كافة عمليات التحقق من الشهادة). في Docker، قم بتثبيت حزمة ca-certificates.

$ curl https://self-signed.example.com/api

أكواد خطأ أخرى

كيفية تصحيح أخطاء curl

عندما يفشل curl، تساعدك هذه الأعلام الثلاثة في تحديد السبب الجذري بسرعة — من دقة DNS إلى مصافحة SSL إلى حمولة الاستجابة.

1. 1

   تمكين المخرجات التفصيلية

   قم بتشغيل curl -v URL لرؤية دورة الطلب/الاستجابة الكاملة: دقة DNS، اتصال TCP، مصافحة TLS، رؤوس الطلب المرسلة، ورؤوس الاستجابة المستلمة. هذا هو العلم الأكثر فائدة لتصحيح الأخطاء.

2. 2

   التحقق من رمز حالة HTTP

   قم بتشغيل curl -o /dev/null -s -w "%{http_code}" URL للحصول على رمز حالة HTTP فقط (200، 404، 500، إلخ) بدون جسم الاستجابة. مفيد لفحوصات الصحة السريعة والبرمجة النصية.

3. 3

   إظهار الأخطاء بصمت

   قم بتشغيل curl -sS URL لإخفاء شريط التقدم (-s) مع الاستمرار في إظهار الأخطاء (-S). مثالي للبرامج النصية حيث تريد مخرجات نظيفة ولكنك تحتاج إلى التقاط الإخفاقات.

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