Mã lỗi curl: Tra cứu đầy đủ

Bảng tra cứu nhanh

Lỗi 6: Không thể phân giải máy chủ

Ý nghĩa

Terminal của bạn hiển thị curl: (6) Could not resolve host. curl không thể phân giải tên máy chủ thành địa chỉ IP — quá trình tra cứu DNS thất bại trước khi bất kỳ kết nối nào được thực hiện.

Nguyên nhân

Các nguyên nhân phổ biến nhất là: lỗi chính tả trong tên máy chủ (ví dụ: curl https://apiexample.com thay vì api.example.com), sự cố máy chủ DNS (DNS được cấu hình bị lỗi hoặc không thể truy cập), không có kết nối mạng (Wi-Fi bị ngắt, VPN chưa kết nối), hoặc tên miền thực sự không tồn tại.

Cách khắc phục

Đầu tiên, kiểm tra xem URL có đúng không. Sau đó kiểm tra phân giải DNS trực tiếp: nslookup api.example.com hoặc dig api.example.com. Nếu DNS thất bại, hãy thử máy chủ DNS khác: curl --dns-servers 8.8.8.8 https://api.example.com. Kiểm tra /etc/resolv.conf hoặc cài đặt mạng của bạn. Nếu đang ở sau VPN công ty, đảm bảo DNS nội bộ có thể phân giải máy chủ.

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

Lỗi 7: Kết nối thất bại

Ý nghĩa

Terminal của bạn hiển thị curl: (7) Failed to connect to host port: Connection refused. curl đã phân giải tên máy chủ nhưng không thể thiết lập kết nối TCP đến máy chủ — kết nối bị từ chối hoặc hết thời gian ở cấp TCP.

Nguyên nhân

Các nguyên nhân phổ biến bao gồm: máy chủ đang ngừng hoạt động hoặc không chạy, tường lửa đang chặn cổng (kiểm tra cả tường lửa cục bộ và phía máy chủ), cổng sai (ví dụ: dịch vụ chạy trên 8080 nhưng bạn đang kết nối đến 443), hoặc hàng đợi lắng nghe của máy chủ đầy do tải nặng.

Cách khắc phục

Xác minh máy chủ đang chạy: ping api.example.com và telnet api.example.com 443. Kiểm tra cổng đúng đang mở: nmap -p 443 api.example.com. Tạm thời tắt tường lửa cục bộ để kiểm tra. Nếu sử dụng Docker, đảm bảo cổng container đã được publish. Thử với chế độ chi tiết: curl -v https://api.example.com để xem chính xác kết nối thất bại ở đâu.

$ curl https://localhost:8080/api

Lỗi 22: HTTP trả về lỗi

Ý nghĩa

Terminal của bạn hiển thị curl: (22) The requested URL returned error. Máy chủ trả về mã trạng thái lỗi HTTP (4xx hoặc 5xx) và curl được gọi với -f hoặc --fail, yêu cầu curl coi lỗi HTTP là thất bại.

Nguyên nhân

Lỗi này được kích hoạt bởi mã trạng thái HTTP như 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found) hoặc 500 (Internal Server Error) — nhưng chỉ khi sử dụng --fail. Nếu không có --fail, curl thoát với mã 0 ngay cả khi gặp lỗi HTTP. Nguyên nhân phổ biến: URL sai, thiếu xác thực, không đủ quyền hoặc lỗi phía máy chủ.

Cách khắc phục

Chạy curl mà không có --fail để xem toàn bộ nội dung phản hồi — thường chứa thông báo lỗi thực tế. Kiểm tra mã trạng thái HTTP: curl -w "%{http_code}" -o /dev/null -s URL. Đối với 401/403: xác minh token xác thực hoặc khóa API. Đối với 404: kiểm tra lại đường dẫn URL. Đối với 500: vấn đề ở phía máy chủ.

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

Lỗi 28: Hết thời gian thao tác

Ý nghĩa

Terminal của bạn hiển thị curl: (28) Operation timed out hoặc curl: (28) Connection timed out. Thao tác mất nhiều thời gian hơn mức cho phép. Đây là lỗi curl phổ biến nhất — nó có thể xảy ra trong quá trình phân giải DNS, kết nối TCP, bắt tay SSL hoặc truyền dữ liệu.

Nguyên nhân

Các nguyên nhân điển hình bao gồm: máy chủ chậm hoặc quá tải không phản hồi kịp thời, tắc nghẽn mạng hoặc mất gói tin, tường lửa âm thầm loại bỏ gói tin (không từ chối, chỉ im lặng), giá trị thời gian chờ quá nghiêm ngặt được đặt với --connect-timeout hoặc --max-time, hoặc cấu hình proxy sai gây ra độ trễ.

Cách khắc phục

Tăng thời gian chờ: curl --connect-timeout 30 --max-time 120 URL. Sử dụng chế độ chi tiết để xem nó bị treo ở đâu: curl -v URL. Kiểm tra độ trễ mạng: ping api.example.com và traceroute api.example.com. Nếu đang qua proxy, thử bỏ qua nó: curl --noproxy '*' URL. Đối với truyền file lớn, cân nhắc sử dụng --retry 3 với --retry-delay 5.

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

Lỗi 35: Lỗi kết nối SSL

Ý nghĩa

Terminal của bạn hiển thị curl: (35) SSL connect error. Quá trình bắt tay SSL/TLS thất bại — curl không thể thiết lập kết nối an toàn với máy chủ.

Nguyên nhân

Các nguyên nhân phổ biến: không khớp phiên bản TLS (máy chủ yêu cầu TLS 1.3 nhưng curl của bạn chỉ hỗ trợ đến TLS 1.2), không tương thích bộ mã hóa, cấu hình SSL máy chủ sai (chứng chỉ hết hạn xuất hiện trong bắt tay, chuỗi không đầy đủ), máy chủ thực sự không hỗ trợ HTTPS trên cổng đã cho, hoặc proxy hoặc tường lửa đang chặn kết nối SSL (MITM).

Cách khắc phục

Bắt buộc phiên bản TLS cụ thể: curl --tlsv1.2 URL hoặc curl --tlsv1.3 URL. Kiểm tra máy chủ hỗ trợ gì: openssl s_client -connect api.example.com:443. Cập nhật curl và OpenSSL lên phiên bản mới nhất. Nếu máy chủ sử dụng chứng chỉ tự ký, đây thường là lỗi 60 — lỗi 35 thường chỉ ra lỗi bắt tay ở cấp giao thức.

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

Lỗi 56: Lỗi nhận dữ liệu — Kết nối bị đặt lại

Ý nghĩa

Terminal của bạn hiển thị curl: (56) Recv failure: Connection reset by peer. Kết nối đã được thiết lập thành công, nhưng việc nhận dữ liệu thất bại — máy chủ đóng hoặc đặt lại kết nối bất ngờ trong quá trình truyền.

Nguyên nhân

Điều này thường xảy ra khi: máy chủ bị crash hoặc khởi động lại giữa quá trình truyền, cân bằng tải hoặc proxy ngắt kết nối (hết thời gian chờ, yêu cầu quá lớn), tường lửa chấm dứt các kết nối dài, máy chủ có thời gian chờ keep-alive ngắn hơn dự kiến, hoặc có gián đoạn mạng giữa client và máy chủ.

Cách khắc phục

Thử lại yêu cầu — các vấn đề mạng tạm thời là nguyên nhân phổ biến nhất. Sử dụng chế độ chi tiết: curl -v URL để xem điểm thất bại chính xác. Nếu lỗi xảy ra trong quá trình tải lên lớn, thử truyền phân đoạn: curl -H "Transfer-Encoding: chunked" URL. Đối với hoạt động Git hiển thị RPC failed; curl 56, tăng bộ đệm: git config http.postBuffer 524288000.

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

Lỗi 60: Vấn đề chứng chỉ SSL

Ý nghĩa

Terminal của bạn hiển thị curl: (60) SSL certificate problem: unable to get local issuer certificate. curl không thể xác minh chứng chỉ SSL của máy chủ với gói CA (Certificate Authority). Quá trình bắt tay TLS đã hoàn thành ở cấp giao thức, nhưng xác minh chứng chỉ thất bại.

Nguyên nhân

Các nguyên nhân phổ biến nhất: máy chủ sử dụng chứng chỉ tự ký, chứng chỉ đã hết hạn, chuỗi chứng chỉ không đầy đủ (thiếu chứng chỉ trung gian), gói CA của curl đã lỗi thời (phổ biến trên hệ thống cũ hoặc trong container Docker), hoặc Common Name / SAN của chứng chỉ không khớp với tên máy chủ được yêu cầu.

Cách khắc phục

Cập nhật gói CA: curl --cacert /path/to/cacert.pem URL. Tải gói cập nhật từ https://curl.se/ca/cacert.pem. Để chẩn đoán: openssl s_client -connect api.example.com:443 -showcerts. Đối với chứng chỉ tự ký trong phát triển, sử dụng curl -k URL (không bao giờ dùng trong sản phẩm — nó vô hiệu hóa toàn bộ xác minh chứng chỉ). Trong Docker, cài gói ca-certificates.

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

Các mã lỗi khác

Cách gỡ lỗi curl

Khi curl thất bại, ba cờ này giúp bạn nhanh chóng xác định nguyên nhân gốc — từ phân giải DNS đến bắt tay SSL đến nội dung phản hồi.

1. 1

   Bật đầu ra chi tiết

   Chạy curl -v URL để xem toàn bộ chu trình yêu cầu/phản hồi: phân giải DNS, kết nối TCP, bắt tay TLS, header yêu cầu đã gửi và header phản hồi nhận được. Đây là cờ gỡ lỗi hữu ích nhất.

2. 2

   Kiểm tra mã trạng thái HTTP

   Chạy curl -o /dev/null -s -w "%{http_code}" URL để chỉ lấy mã trạng thái HTTP (200, 404, 500, v.v.) mà không có nội dung phản hồi. Hữu ích cho kiểm tra nhanh và viết script.

3. 3

   Hiển thị lỗi im lặng

   Chạy curl -sS URL để ẩn thanh tiến trình (-s) nhưng vẫn hiển thị lỗi (-S). Hoàn hảo cho script khi bạn muốn đầu ra sạch nhưng cần phát hiện lỗi.

Câu hỏi thường gặp