کدهای خطای 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 متصل می‌شوید)، یا صف انتظار سرور پر است تحت بار سنگین.

نحوه رفع

بررسی کنید که سرور در حال اجرا است: ping api.example.com و telnet api.example.com 443. بررسی کنید پورت صحیح باز است: nmap -p 443 api.example.com. فایروال محلی را به صورت موقت غیرفعال کنید. اگر از Docker استفاده می‌کنید، مطمئن شوید پورت کانتینر منتشر شده است. با حالت verbose امتحان کنید: 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 (درخواست نامعتبر)، 401 (غیرمجاز)، 403 (ممنوع)، 404 (یافت نشد) یا 500 (خطای داخلی سرور) ایجاد می‌شود — اما فقط زمانی که --fail استفاده شود. بدون --fail، curl حتی در خطاهای HTTP با کد 0 خارج می‌شود. دلایل رایج: URL اشتباه، عدم احراز هویت، مجوزهای ناکافی یا باگ‌های سمت سرور.

نحوه رفع

curl را بدون --fail اجرا کنید تا بدنه کامل پاسخ را ببینید — اغلب حاوی پیام خطای واقعی است. کد وضعیت HTTP را بررسی کنید: curl -w "%{http_code}" -o /dev/null -s URL. برای 401/403: توکن احراز هویت یا کلید API خود را تأیید کنید. برای 404: مسیر URL را دوباره بررسی کنید. برای 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. از حالت verbose استفاده کنید تا ببینید کجا متوقف می‌شود: 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 پشتیبانی می‌کند)، ناسازگاری مجموعه رمز، پیکربندی نادرست 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 کوتاه‌تر از حد انتظار است، یا یک اختلال شبکه بین کلاینت و سرور وجود دارد.

نحوه رفع

درخواست را دوباره امتحان کنید — مشکلات موقتی شبکه رایج‌ترین دلیل هستند. از حالت verbose استفاده کنید: curl -v URL تا نقطه دقیق شکست را ببینید. اگر خطا در حین آپلودهای بزرگ رخ می‌دهد، انتقال chunked را امتحان کنید: 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

   فعال‌سازی خروجی verbose

   دستور 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) همچنان نمایش داده شوند. مناسب برای اسکریپت‌هایی که خروجی تمیز می‌خواهید اما نیاز به گرفتن خطاها دارید.

سوالات متداول