cURL 函數回傳的錯誤代碼(curl_errno())對應 curl_strerror() 訊息。以下為常見代碼對照,依官方 curl/curl.h 定義整理。
| 代碼 | 常數名稱 | 中文說明 | 常見原因與處理 |
|---|---|---|---|
| 0 | CURLE_OK | 正常完成 | 請求成功 |
| 1 | CURLE_UNSUPPORTED_PROTOCOL | 不支援的協定 | URL 協定錯誤或此版 cURL 未編譯支援該協定 |
| 2 | CURLE_FAILED_INIT | 初始化失敗 | 內部錯誤,嘗試重新建立 handle |
| 3 | CURLE_URL_MALFORMAT | URL 格式錯誤 | URL 語法不合法,檢查編碼與特殊字元 |
| 4 | CURLE_NOT_BUILT_IN | 功能未編譯支援 | 所用功能(如 HTTPS)未在編譯時啟用 |
| 5 | CURLE_COULDNT_RESOLVE_PROXY | 無法解析 Proxy | Proxy 主機名錯誤或 DNS 故障 |
| 6 | CURLE_COULDNT_RESOLVE_HOST | 無法解析主機 | 目標主機名 DNS 解析失敗 |
| 7 | CURLE_COULDNT_CONNECT | 無法連線至主機 | 連線被拒、防火牆阻擋、IP/埠錯誤 |
| 8 | CURLE_FTP_WEIRD_SERVER_REPLY | FTP 異常伺服器回應 | FTP 伺服器回應格式非標準 |
| 9 | CURLE_REMOTE_ACCESS_DENIED | 遠端存取被拒 | FTP 登入失敗或目錄不存在 |
| 11 | CURLE_FTP_WEIRD_PASS_REPLY | FTP PASS 指令異常回應 | 密碼錯誤或伺服器回應異常 |
| 13 | CURLE_FTP_WEIRD_PASV_REPLY | FTP PASV 異常回應 | 被動模式協商失敗 |
| 14 | CURLE_FTP_WEIRD_227_FORMAT | FTP 227 格式錯誤 | 無法解析 PASV 回應的 IP/埠 |
| 15 | CURLE_FTP_CANT_GET_HOST | FTP 無法取得主機 IP | 227 回應中 IP 解析失敗 |
| 17 | CURLE_FTP_COULDNT_SET_BINARY | 無法設定二進制傳輸 | 伺服器不支援 TYPE I 指令 |
| 18 | CURLE_PARTIAL_FILE | 傳輸大小異常 | 下載/上傳位元組數與預期不符 |
| 19 | CURLE_FTP_COULDNT_RETR_FILE | FTP RETR 失敗 | 檔案不存在或權限不足 |
| 21 | CURLE_QUOTE_ERROR | FTP QUOTE 指令錯誤 | 自訂 FTP 指令執行失敗 |
| 22 | CURLE_HTTP_RETURNED_ERROR | HTTP 錯誤回應 (≥400) | 啟用 CURLOPT_FAILONERROR 時觸發 |
| 23 | CURLE_WRITE_ERROR | 寫入資料失敗 | 磁碟滿、權限不足、寫入回呼函數錯誤 |
| 25 | CURLE_UPLOAD_FAILED | 上傳失敗 (STOR) | 伺服器拒絕上傳 |
| 26 | CURLE_READ_ERROR | 讀取資料失敗 | 讀取回呼函數錯誤或檔案不可讀 |
| 27 | CURLE_OUT_OF_MEMORY | 記憶體不足 | 內部配置記憶體失敗 |
| 28 | CURLE_OPERATION_TIMEDOUT | 操作逾時 | 達到 CURLOPT_TIMEOUT 或 CURLOPT_CONNECTTIMEOUT 設定值 |
| 30 | CURLE_FTP_PORT_FAILED | FTP PORT 指令失敗 | 主動模式失敗,建議改用 PASV |
| 31 | CURLE_FTP_COULDNT_USE_REST | FTP REST 指令失敗 | 斷點續傳不支援 |
| 33 | CURLE_RANGE_ERROR | HTTP Range 不支援 | 伺服器不支援斷點下載 |
| 34 | CURLE_HTTP_POST_ERROR | HTTP POST 內部錯誤 | 組裝 POST 請求失敗 |
| 35 | CURLE_SSL_CONNECT_ERROR | SSL/TLS 連線錯誤 | 憑證驗證失敗、協定版本不符、Cipher 不匹配 |
| 36 | CURLE_BAD_DOWNLOAD_RESUME | 斷點續傳異常 | 續傳位移點無效 |
| 37 | CURLE_FILE_COULDNT_READ_FILE | 無法讀取檔案 | 上傳檔案不存在或不可讀 |
| 38 | CURLE_LDAP_CANNOT_BIND | LDAP 綁定失敗 | 認證失敗 |
| 39 | CURLE_LDAP_SEARCH_FAILED | LDAP 搜尋失敗 | 查詢語法錯誤 |
| 41 | CURLE_FUNCTION_NOT_FOUND | 函數未找到 | 內部錯誤,缺少必要函數 |
| 42 | CURLE_ABORTED_BY_CALLBACK | 回呼函數中止 | 進度/寫入/讀取回呼返回錯誤碼 |
| 43 | CURLE_BAD_FUNCTION_ARGUMENT | 函數參數錯誤 | 傳遞給 cURL 函數的參數無效 |
| 45 | CURLE_INTERFACE_FAILED | 介面綁定失敗 | CURLOPT_INTERFACE 指定的介面不可用 |
| 47 | CURLE_TOO_MANY_REDIRECTS | 重導向次數過多 | 超過 CURLOPT_MAXREDIRS 限制 |
| 48 | CURLE_UNKNOWN_OPTION | 未知選項 | 傳遞給 curl_setopt 的選項不存在 |
| 49 | CURLE_TELNET_OPTION_SYNTAX | Telnet 選項語法錯誤 | Telnet 選項格式不正確 |
| 51 | CURLE_SSL_PEER_CERTIFICATE | SSL 對等憑證驗證失敗 | 憑證過期、自簽、主機名不符,可用 CURLOPT_SSL_VERIFYPEER 控制 |
| 52 | CURLE_GOT_NOTHING | 無任何回應 | 伺服器關閉連線未發送資料 |
| 53 | CURLE_SSL_ENGINE_NOTFOUND | 找不到 SSL 引擎 | CURLOPT_SSL_ENGINE 指定引擎不存在 |
| 54 | CURLE_SSL_ENGINE_SETFAILED | SSL 引擎設定失敗 | 引擎初始化失敗 |
| 55 | CURLE_SEND_ERROR | 發送資料失敗 | 網路中斷、發送緩衝區滿 |
| 56 | CURLE_RECV_ERROR | 接收資料失敗 | 網路中斷、接收緩衝區錯誤 |
| 58 | CURLE_SSL_CERTPROBLEM | 客戶端憑證問題 | 客戶端憑證格式錯誤或密碼錯誤 |
| 59 | CURLE_SSL_CIPHER | 無法使用指定 Cipher | CURLOPT_SSL_CIPHER_LIST 指定的加密套件不支援 |
| 60 | CURLE_SSL_CACERT | CA 憑證驗證失敗 | CURLOPT_CAINFO 路徑錯誤或 CA 不受信 |
| 61 | CURLE_BAD_CONTENT_ENCODING | 不支援的內容編碼 | 伺服器回傳未知 Content-Encoding |
| 63 | CURLE_FILESIZE_EXCEEDED | 檔案大小超過限制 | 超過 CURLOPT_MAXFILESIZE |
| 64 | CURLE_USE_SSL_FAILED | 無法啟用 SSL | FTP over SSL/TLS 協商失敗 |
| 65 | CURLE_SEND_FAIL_REWIND | 發送失敗需倒帶失敗 | 上傳資料流無法重置 |
| 66 | CURLE_SSL_ENGINE_INITFAILED | SSL 引擎初始化失敗 | 引擎啟動錯誤 |
| 67 | CURLE_LOGIN_DENIED | 登入被拒 | 認證失敗(非 FTP) |
| 68 | CURLE_TFTP_NOTFOUND | TFTP 檔案不存在 | TFTP 伺服器找不到檔案 |
| 69 | CURLE_TFTP_PERM | TFTP 權限不足 | TFTP 讀寫權限錯誤 |
| 70 | CURLE_TFTP_DISKFULL | TFTP 磁碟滿 | 伺服器磁碟空間不足 |
| 71 | CURLE_TFTP_ILLEGAL | TFTP 非法操作 | TFTP 協定錯誤 |
| 72 | CURLE_TFTP_UNKNOWNID | TFTP 未知傳輸 ID | 內部錯誤 |
| 73 | CURLE_TFTP_EXISTS | TFTP 檔案已存在 | 建立檔案失敗 |
| 74 | CURLE_TFTP_NOSUCHUSER | TFTP 用戶不存在 | TFTP 認證失敗 |
| 75 | CURLE_CONV_FAILED | 字元轉換失敗 | CURLOPT_CONV_* 相關轉換錯誤 |
| 76 | CURLE_CONV_REQD | 需要字元轉換 | 缺少必要轉換函數 |
| 77 | CURLE_SSL_CACERT_BADFILE | CA 憑證檔案讀取失敗 | CURLOPT_CAINFO/CAPATH 檔案損壞 |
| 78 | CURLE_REMOTE_FILE_NOT_FOUND | 遠端檔案不存在 | HTTP 404 或 FTP 找不到檔案 |
| 79 | CURLE_SSH | SSH 內部錯誤 | SCP/SFTP 協定層錯誤 |
| 80 | CURLE_SSH_KNOWN_HOSTS | SSH known_hosts 驗證失敗 | 主機金鑰不匹配 |
| 81 | CURLE_SSH_AUTH_FAILED | SSH 認證失敗 | 公鑰/密碼認證失敗 |
| 82 | CURLE_SSH_LIBRARY | SSH 函式庫錯誤 | libssh2 內部錯誤 |
| 83 | CURLE_SSH_PUBLIC_KEY | SSH 公鑰檔案錯誤 | 公鑰讀取失敗 |
| 84 | CURLE_SSH_PRIVATE_KEY | SSH 私鑰檔案錯誤 | 私鑰讀取失敗或密語錯誤 |
| 85 | CURLE_SSL_SHUTDOWN_FAILED | SSL 關閉失敗 | SSL 連線關閉異常 |
| 86 | CURLE_AGAIN | 需重試 | 非阻塞模式下資源暫時不可用 |
| 87 | CURLE_SSL_CRL_BADFILE | CRL 檔案讀取失敗 | CURLOPT_CRLFILE 檔案損壞 |
| 88 | CURLE_SSL_ISSUER_ERROR | 簽發者驗證失敗 | 憑證簽發者不符合 CURLOPT_SSL_VERIFYSTATUS |
| 89 | CURLE_SSL_PINNEDPUBKEYNOTMATCH | 釘選公鑰不匹配 | CURLOPT_PINNEDPUBLICKEY 驗證失敗 |
| 90 | CURLE_SSL_INVALIDCERTSTATUS | 憑證狀態無效 | OCSP 驗證失敗 |
| 91 | CURLE_HTTP2_STREAM | HTTP/2 流錯誤 | 流被重置或關閉 |
| 92 | CURLE_HTTP2 | HTTP/2 協定錯誤 | HTTP/2 層面錯誤 |
| 93 | CURLE_HTTP3 | HTTP/3 (QUIC) 錯誤 | QUIC 協定錯誤 |
| 94 | CURLE_QUIC_CONNECT_ERROR | QUIC 連線錯誤 | QUIC 握手失敗 |
$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() 回傳值是否為 falseCURLOPT_FAILONERROR 讓 HTTP 4xx/5xx 觸發 CURLE_HTTP_RETURNED_ERRORCURLOPT_TIMEOUT 與 CURLOPT_CONNECTTIMEOUTCURLOPT_SSL_VERIFYPEER = true)