您现在的位置：程式碼之家 >> 編程語言 > >> 網頁程式設計 >> PHP 程式設計 >> PHP 相關知識

cURL 錯誤代碼完整對照表（0-83）

編輯：PHP 相關知識

cURL 函數回傳的錯誤代碼（curl_errno()）對應具體失敗原因。本文提供官方代碼 0-83 完整對照表，含中文說明與排查方向。

代碼	常數名	中文說明	排查方向
0	CURLE_OK	正常完成	—
1	CURLE_UNSUPPORTED_PROTOCOL	不支援的協定	檢查 URL 協定拼寫、libcurl 編譯支援
2	CURLE_FAILED_INIT	初始化失敗	記憶體不足、內部錯誤
3	CURLE_URL_MALFORMAT	URL 格式錯誤	URL 語法檢查、特殊字元編碼
4	CURLE_NOT_BUILT_IN	未編譯支援的功能	重新編譯 libcurl 啟用對應協定
5	CURLE_COULDNT_RESOLVE_PROXY	無法解析代理主機	代理 DNS、主機名拼寫
6	CURLE_COULDNT_RESOLVE_HOST	無法解析目標主機	DNS 解析、/etc/hosts、網路通暢
7	CURLE_COULDNT_CONNECT	無法連線到主機	防火牆、埠開放、IP/埠正確性
8	CURLE_FTP_WEIRD_SERVER_REPLY	FTP 伺服器異常回應	FTP 伺服器配置、被動模式
9	CURLE_REMOTE_ACCESS_DENIED	存取被拒絕	帳號密碼、權限、目錄存在性
11	CURLE_FTP_WEIRD_PASS_REPLY	FTP PASS 指令異常回應	密碼正確性、伺服器日誌
13	CURLE_FTP_WEIRD_PASV_REPLY	FTP PASV 異常回應	被動模式埠範圍、防火牆
14	CURLE_FTP_WEIRD_227_FORMAT	FTP 227 格式錯誤	伺服器回應解析、libcurl 版本
15	CURLE_FTP_CANT_GET_HOST	無法從 227 取得主機 IP	PASV 回應 IP 可達性
17	CURLE_FTP_COULDNT_SET_TYPE	無法設定二進制傳輸	伺服器支援 TYPE I
18	CURLE_PARTIAL_FILE	傳輸不完整	網路中斷、伺服器斷點續傳支援
19	CURLE_FTP_COULDNT_RETR_FILE	RETR 失敗（無法下載）	檔案存在、權限、路徑正確
21	CURLE_QUOTE_ERROR	QUOTE 指令錯誤	預執行指令語法、伺服器支援
22	CURLE_HTTP_RETURNED_ERROR	HTTP 錯誤狀態碼 (>=400)	配合 CURLOPT_FAILONERROR，檢查 HTTP 回應
23	CURLE_WRITE_ERROR	寫入本地失敗	磁碟空間、權限、路徑可寫
25	CURLE_UPLOAD_FAILED	上傳失敗 (STOR)	伺服器寫入權限、磁碟配額
26	CURLE_READ_ERROR	讀取本地檔案失敗	檔案存在、權限、路徑正確
27	CURLE_OUT_OF_MEMORY	記憶體不足	大檔案上傳/下載、記憶體限制
28	CURLE_OPERATION_TIMEDOUT	操作逾時	調整 CURLOPT_TIMEOUT/CONNECTTIMEOUT、網路延遲
30	CURLE_FTP_PORT_FAILED	PORT 指令失敗	改用 PASV 模式 (CURLOPT_FTPPASV)
31	CURLE_FTP_COULDNT_USE_REST	REST 指令失敗	伺服器支援斷點續傳
33	CURLE_RANGE_ERROR	HTTP Range 不支援	伺服器支援斷點下載
34	CURLE_HTTP_POST_ERROR	內部 POST 錯誤	CURLOPT_POSTFIELDS 格式、大小
35	CURLE_SSL_CONNECT_ERROR	SSL/TLS 連線錯誤	憑證驗證、CA 憑證路徑、協定版本
36	CURLE_FTP_BAD_DOWNLOAD_RESUME	續傳損壞	檔案大小一致性、伺服器支援
37	CURLE_FILE_COULDNT_READ_FILE	檔案無法讀取	權限、路徑、檔案存在
38	CURLE_LDAP_CANNOT_BIND	LDAP 綁定失敗	DN、密碼、伺服器可達
39	CURLE_LDAP_SEARCH_FAILED	LDAP 搜尋失敗	過濾器語法、基礎 DN
41	CURLE_FUNCTION_NOT_FOUND	LDAP 函數缺失	libcurl 編譯支援 LDAP
42	CURLE_ABORTED_BY_CALLBACK	回調中止	進度/寫入/讀取回調返回錯誤
43	CURLE_BAD_FUNCTION_ARGUMENT	內部錯誤參數	libcurl Bug、升級版本
45	CURLE_INTERFACE_FAILED	介面錯誤（指定介面失敗）	CURLOPT_INTERFACE IP/介面名正確
47	CURLE_TOO_MANY_REDIRECTS	重導向過多	調整 CURLOPT_MAXREDIRS、檢查迴圈
48	CURLE_UNKNOWN_OPTION	未知選項	選項拼寫、libcurl 版本支援
49	CURLE_TELNET_OPTION_SYNTAX	TELNET 選項語法錯誤	選項格式
51	CURLE_SSL_PEER_CERTIFICATE	Peer 憑證驗證失敗	CA 憑證、憑證鏈、主機名驗證
52	CURLE_GOT_NOTHING	伺服器無回應	伺服器存活、網路、防火牆
53	CURLE_SSL_ENGINE_NOTFOUND	SSL 引擎未找到	引擎名稱、libcurl 編譯
54	CURLE_SSL_ENGINE_SETFAILED	設定 SSL 引擎失敗	引擎初始化
55	CURLE_SEND_ERROR	發送網路資料失敗	網路中斷、MTU、防火牆
56	CURLE_RECV_ERROR	接收網路資料失敗	網路中斷、伺服器關閉連線
58	CURLE_SSL_CERTPROBLEM	本地客戶端憑證問題	憑證檔案、密碼、格式
59	CURLE_SSL_CIPHER	無法使用指定加密套件	CURLOPT_SSL_CIPHER_LIST 支援性
60	CURLE_SSL_CACERT	CA 憑證驗證失敗	CURLOPT_CAINFO/CAPATH 路徑正確
61	CURLE_BAD_CONTENT_ENCODING	無法識別傳輸編碼	Content-Encoding 標頭、libcurl 支援
62	CURLE_LDAP_INVALID_URL	無效 LDAP URL	URL 格式
63	CURLE_FILESIZE_EXCEEDED	檔案超過最大限制	CURLOPT_MAXFILESIZE 設定
64	CURLE_FTP_SSL_FAILED	FTP SSL 層級失敗	CURLOPT_FTP_SSL 設定、伺服器支援
65	CURLE_SEND_FAIL_REWIND	回卷失敗	大檔案上傳、seek 失敗
66	CURLE_SSL_ENGINE_INITFAILED	SSL 引擎初始化失敗	引擎支援、參數
67	CURLE_LOGIN_DENIED	登入被拒絕	帳號、密碼、認證方式
68	CURLE_TFTP_NOTFOUND	TFTP 檔案不存在	檔案路徑
69	CURLE_TFTP_PERM	TFTP 權限問題	讀寫權限
70	CURLE_TFTP_DISKFULL	TFTP 磁碟滿	伺服器磁碟空間
71	CURLE_TFTP_ILLEGAL	非法 TFTP 操作	操作序列
72	CURLE_TFTP_UNKNOWNID	未知 TFTP 傳輸 ID	內部錯誤
73	CURLE_TFTP_EXISTS	TFTP 檔案已存在	覆蓋策略
74	CURLE_TFTP_NOSUCHUSER	TFTP 無此用戶	用戶認證
75	CURLE_CONV_FAILED	字元轉換失敗	CURLOPT_CONV_* 回調、編碼支援
76	CURLE_CONV_REQD	需要字元轉換功能	libcurl 編譯支援 iconv
77	CURLE_SSL_CACERT_BADFILE	CA 憑證檔案讀取問題	路徑、權限、格式
78	CURLE_REMOTE_FILE_NOT_FOUND	URL 引用資源不存在	404、路徑正確
79	CURLE_SSH	SSH 會話錯誤	SSH 金鑰、伺服器配置
80	CURLE_SSL_SHUTDOWN_FAILED	關閉 SSL 連線失敗	OpenSSL 版本、協定
81	CURLE_AGAIN	服務未就緒	非阻塞模式、重試
82	CURLE_SSL_CRL_BADFILE	CRL 檔案讀取失敗	路徑、格式
83	CURLE_SSL_ISSUER_ERROR	簽發者驗證失敗	憑證鏈、CA 信任

使用建議

程式中永遠檢查 curl_errno($ch) 並記錄 curl_error($ch) 訊息。
針對 6, 7, 28, 35, 60 等高頻錯誤建立自動重試與告警機制。
SSL/TLS 相關錯誤 (35, 51, 53, 54, 58, 59, 60, 64, 66, 77, 80, 82, 83) 需確保 CA 憑證束最新（cacert.pem）。
生產環境啟用 CURLOPT_VERBOSE 並導向日誌，關鍵失敗時可還原完整握手細節。

收藏此表，遇到 cURL 異常可秒級定位根因。