萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

cURL 錯誤代碼完整對照表(libcurl 官方定義)

cURL 函數回傳的錯誤代碼(curl_errno())對應 curl_strerror() 訊息。以下為常見代碼對照,依官方 curl/curl.h 定義整理。

代碼常數名稱中文說明常見原因與處理
0CURLE_OK正常完成請求成功
1CURLE_UNSUPPORTED_PROTOCOL不支援的協定URL 協定錯誤或此版 cURL 未編譯支援該協定
2CURLE_FAILED_INIT初始化失敗內部錯誤,嘗試重新建立 handle
3CURLE_URL_MALFORMATURL 格式錯誤URL 語法不合法,檢查編碼與特殊字元
4CURLE_NOT_BUILT_IN功能未編譯支援所用功能(如 HTTPS)未在編譯時啟用
5CURLE_COULDNT_RESOLVE_PROXY無法解析 ProxyProxy 主機名錯誤或 DNS 故障
6CURLE_COULDNT_RESOLVE_HOST無法解析主機目標主機名 DNS 解析失敗
7CURLE_COULDNT_CONNECT無法連線至主機連線被拒、防火牆阻擋、IP/埠錯誤
8CURLE_FTP_WEIRD_SERVER_REPLYFTP 異常伺服器回應FTP 伺服器回應格式非標準
9CURLE_REMOTE_ACCESS_DENIED遠端存取被拒FTP 登入失敗或目錄不存在
11CURLE_FTP_WEIRD_PASS_REPLYFTP PASS 指令異常回應密碼錯誤或伺服器回應異常
13CURLE_FTP_WEIRD_PASV_REPLYFTP PASV 異常回應被動模式協商失敗
14CURLE_FTP_WEIRD_227_FORMATFTP 227 格式錯誤無法解析 PASV 回應的 IP/埠
15CURLE_FTP_CANT_GET_HOSTFTP 無法取得主機 IP227 回應中 IP 解析失敗
17CURLE_FTP_COULDNT_SET_BINARY無法設定二進制傳輸伺服器不支援 TYPE I 指令
18CURLE_PARTIAL_FILE傳輸大小異常下載/上傳位元組數與預期不符
19CURLE_FTP_COULDNT_RETR_FILEFTP RETR 失敗檔案不存在或權限不足
21CURLE_QUOTE_ERRORFTP QUOTE 指令錯誤自訂 FTP 指令執行失敗
22CURLE_HTTP_RETURNED_ERRORHTTP 錯誤回應 (≥400)啟用 CURLOPT_FAILONERROR 時觸發
23CURLE_WRITE_ERROR寫入資料失敗磁碟滿、權限不足、寫入回呼函數錯誤
25CURLE_UPLOAD_FAILED上傳失敗 (STOR)伺服器拒絕上傳
26CURLE_READ_ERROR讀取資料失敗讀取回呼函數錯誤或檔案不可讀
27CURLE_OUT_OF_MEMORY記憶體不足內部配置記憶體失敗
28CURLE_OPERATION_TIMEDOUT操作逾時達到 CURLOPT_TIMEOUT 或 CURLOPT_CONNECTTIMEOUT 設定值
30CURLE_FTP_PORT_FAILEDFTP PORT 指令失敗主動模式失敗,建議改用 PASV
31CURLE_FTP_COULDNT_USE_RESTFTP REST 指令失敗斷點續傳不支援
33CURLE_RANGE_ERRORHTTP Range 不支援伺服器不支援斷點下載
34CURLE_HTTP_POST_ERRORHTTP POST 內部錯誤組裝 POST 請求失敗
35CURLE_SSL_CONNECT_ERRORSSL/TLS 連線錯誤憑證驗證失敗、協定版本不符、Cipher 不匹配
36CURLE_BAD_DOWNLOAD_RESUME斷點續傳異常續傳位移點無效
37CURLE_FILE_COULDNT_READ_FILE無法讀取檔案上傳檔案不存在或不可讀
38CURLE_LDAP_CANNOT_BINDLDAP 綁定失敗認證失敗
39CURLE_LDAP_SEARCH_FAILEDLDAP 搜尋失敗查詢語法錯誤
41CURLE_FUNCTION_NOT_FOUND函數未找到內部錯誤,缺少必要函數
42CURLE_ABORTED_BY_CALLBACK回呼函數中止進度/寫入/讀取回呼返回錯誤碼
43CURLE_BAD_FUNCTION_ARGUMENT函數參數錯誤傳遞給 cURL 函數的參數無效
45CURLE_INTERFACE_FAILED介面綁定失敗CURLOPT_INTERFACE 指定的介面不可用
47CURLE_TOO_MANY_REDIRECTS重導向次數過多超過 CURLOPT_MAXREDIRS 限制
48CURLE_UNKNOWN_OPTION未知選項傳遞給 curl_setopt 的選項不存在
49CURLE_TELNET_OPTION_SYNTAXTelnet 選項語法錯誤Telnet 選項格式不正確
51CURLE_SSL_PEER_CERTIFICATESSL 對等憑證驗證失敗憑證過期、自簽、主機名不符,可用 CURLOPT_SSL_VERIFYPEER 控制
52CURLE_GOT_NOTHING無任何回應伺服器關閉連線未發送資料
53CURLE_SSL_ENGINE_NOTFOUND找不到 SSL 引擎CURLOPT_SSL_ENGINE 指定引擎不存在
54CURLE_SSL_ENGINE_SETFAILEDSSL 引擎設定失敗引擎初始化失敗
55CURLE_SEND_ERROR發送資料失敗網路中斷、發送緩衝區滿
56CURLE_RECV_ERROR接收資料失敗網路中斷、接收緩衝區錯誤
58CURLE_SSL_CERTPROBLEM客戶端憑證問題客戶端憑證格式錯誤或密碼錯誤
59CURLE_SSL_CIPHER無法使用指定 CipherCURLOPT_SSL_CIPHER_LIST 指定的加密套件不支援
60CURLE_SSL_CACERTCA 憑證驗證失敗CURLOPT_CAINFO 路徑錯誤或 CA 不受信
61CURLE_BAD_CONTENT_ENCODING不支援的內容編碼伺服器回傳未知 Content-Encoding
63CURLE_FILESIZE_EXCEEDED檔案大小超過限制超過 CURLOPT_MAXFILESIZE
64CURLE_USE_SSL_FAILED無法啟用 SSLFTP over SSL/TLS 協商失敗
65CURLE_SEND_FAIL_REWIND發送失敗需倒帶失敗上傳資料流無法重置
66CURLE_SSL_ENGINE_INITFAILEDSSL 引擎初始化失敗引擎啟動錯誤
67CURLE_LOGIN_DENIED登入被拒認證失敗(非 FTP)
68CURLE_TFTP_NOTFOUNDTFTP 檔案不存在TFTP 伺服器找不到檔案
69CURLE_TFTP_PERMTFTP 權限不足TFTP 讀寫權限錯誤
70CURLE_TFTP_DISKFULLTFTP 磁碟滿伺服器磁碟空間不足
71CURLE_TFTP_ILLEGALTFTP 非法操作TFTP 協定錯誤
72CURLE_TFTP_UNKNOWNIDTFTP 未知傳輸 ID內部錯誤
73CURLE_TFTP_EXISTSTFTP 檔案已存在建立檔案失敗
74CURLE_TFTP_NOSUCHUSERTFTP 用戶不存在TFTP 認證失敗
75CURLE_CONV_FAILED字元轉換失敗CURLOPT_CONV_* 相關轉換錯誤
76CURLE_CONV_REQD需要字元轉換缺少必要轉換函數
77CURLE_SSL_CACERT_BADFILECA 憑證檔案讀取失敗CURLOPT_CAINFO/CAPATH 檔案損壞
78CURLE_REMOTE_FILE_NOT_FOUND遠端檔案不存在HTTP 404 或 FTP 找不到檔案
79CURLE_SSHSSH 內部錯誤SCP/SFTP 協定層錯誤
80CURLE_SSH_KNOWN_HOSTSSSH known_hosts 驗證失敗主機金鑰不匹配
81CURLE_SSH_AUTH_FAILEDSSH 認證失敗公鑰/密碼認證失敗
82CURLE_SSH_LIBRARYSSH 函式庫錯誤libssh2 內部錯誤
83CURLE_SSH_PUBLIC_KEYSSH 公鑰檔案錯誤公鑰讀取失敗
84CURLE_SSH_PRIVATE_KEYSSH 私鑰檔案錯誤私鑰讀取失敗或密語錯誤
85CURLE_SSL_SHUTDOWN_FAILEDSSL 關閉失敗SSL 連線關閉異常
86CURLE_AGAIN需重試非阻塞模式下資源暫時不可用
87CURLE_SSL_CRL_BADFILECRL 檔案讀取失敗CURLOPT_CRLFILE 檔案損壞
88CURLE_SSL_ISSUER_ERROR簽發者驗證失敗憑證簽發者不符合 CURLOPT_SSL_VERIFYSTATUS
89CURLE_SSL_PINNEDPUBKEYNOTMATCH釘選公鑰不匹配CURLOPT_PINNEDPUBLICKEY 驗證失敗
90CURLE_SSL_INVALIDCERTSTATUS憑證狀態無效OCSP 驗證失敗
91CURLE_HTTP2_STREAMHTTP/2 流錯誤流被重置或關閉
92CURLE_HTTP2HTTP/2 協定錯誤HTTP/2 層面錯誤
93CURLE_HTTP3HTTP/3 (QUIC) 錯誤QUIC 協定錯誤
94CURLE_QUIC_CONNECT_ERRORQUIC 連線錯誤QUIC 握手失敗

PHP 中獲取錯誤資訊

$ch = curl_init('https://api.example.com');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

if ($response === false) {
    $errno = curl_errno($ch);
    $error = curl_error($ch);
    echo "cURL Error ($errno): $error\n";
    // 可對照上表處理
} else {
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    // 處理 HTTP 狀態碼
}
curl_close($ch);

最佳實務

  • 永遠檢查 curl_exec() 回傳值是否為 false
  • 啟用 CURLOPT_FAILONERROR 讓 HTTP 4xx/5xx 觸發 CURLE_HTTP_RETURNED_ERROR
  • 設定合理的 CURLOPT_TIMEOUT 與 CURLOPT_CONNECTTIMEOUT
  • 生產環境務必驗證 SSL 憑證(CURLOPT_SSL_VERIFYPEER = true)
  • 記錄完整錯誤碼與訊息以利除錯
copyright © 萬盛學電腦網 all rights reserved