קודי שגיאה של 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, ודא שפורט הקונטיינר פורסם. נסה עם מצב מפורט: 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. סיבות נפוצות: 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, או העברת נתונים.

סיבות

סיבות טיפוסיות כוללות: שרת איטי או עמוס שלא מגיב בזמן, עומס ברשת או אובדן מנות, חומת אש שמשמיטה מנות בשקט (ללא דחייה, רק שתיקה), ערכי timeout מחמירים מדי שהוגדרו עם --connect-timeout או --max-time, או תצורת proxy שגויה שגורמת לעיכובים.

איך לתקן

הגדל את ה-timeout: curl --connect-timeout 30 --max-time 120 URL. השתמש במצב מפורט כדי לראות היכן הוא תקוע: curl -v URL. בדוק השהיית רשת: ping api.example.com ו-traceroute api.example.com. אם מאחורי proxy, נסה לעקוף אותו: 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 על הפורט הנתון, או proxy או חומת אש מיירטים את חיבור ה-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. החיבור נוצר בהצלחה, אך קבלת הנתונים נכשלה — השרת סגר או איפס את החיבור באופן בלתי צפוי במהלך ההעברה.

סיבות

זה קורה לעתים קרובות כאשר: השרת קורס או מתאתחל באמצע ההעברה, מאזן עומסים או proxy מנתק את החיבור (timeout של חוסר פעילות, בקשה גדולה מדי), חומת אש מפסיקה חיבורים ארוכי-חיים, לשרת יש timeout של keep-alive קצר יותר מהצפוי, או שיש הפרעה ברשת בין הלקוח לשרת.

איך לתקן

נסה את הבקשה שוב — בעיות רשת חולפות הן הסיבה הנפוצה ביותר. השתמש במצב מפורט: curl -v URL כדי לראות את נקודת הכשל המדויקת. אם השגיאה מתרחשת במהלך העלאות גדולות, נסה העברה בחלקים: 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). מושלם לסקריפטים שבהם רוצים פלט נקי אך צריכים לתפוס כשלונות.

שאלות נפוצות