英文: libcurl error codes

中文: libcurl 错误码参照

libcurl-errors - libcurl 中的错误代码

描述

本手册页涵盖了 libcurl 中大多数（即使不是全部）可用的错误代码。此外，还介绍了错误发生的原因以及可能的解决方法。

Curlcode

几乎所有“easy”接口函数都会返回 CURLcode 错误代码。无论如何，使用curl_easy_setopt选项CURLOPT_ERRORBUFFER都是一个好主意，因为它会返回一个易于阅读的错误字符串，除了错误代码之外，它还能提供更多关于错误原因的详细信息。您可以调用curl_easy_strerror来根据给定的 CURLcode 编号获取错误字符串。

CURLcode 是下列之一：

CURLE_OK (0)

一切顺利。一切照常进行。

CURLE_UNSUPPORTED_PROTOCOL (1)

您传递给 libcurl 的 URL 使用了 libcurl 不支持的协议。该协议可能是一个您未使用的编译时选项，也可能是一个拼写错误的协议字符串，或者 libcurl 没有代码支持的协议。

CURLE_FAILED_INIT (2)

早期初始化代码失败。这可能是内部错误或问题，也可能是资源问题，导致初始化时无法完成一些基本操作。

CURLE_URL_MALFORMAT (3)

URL 格式不正确。

CURLE_NOT_BUILT_IN (4)

由于构建时决策，此 libcurl 中未找到所请求的功能、协议或选项。这意味着在构建 libcurl 时未启用或明确禁用某个功能或选项，因此为了使其正常运行，您必须重新构建 libcurl。

CURLE_COULDNT_RESOLVE_PROXY (5)

无法解析代理。无法解析给定的代理主机。

CURLE_COULDNT_RESOLVE_HOST (6)

无法解析主机。指定的远程主机未解析。

CURLE_COULDNT_CONNECT (7)

无法连接到主机或代理。

CURLE_WEIRD_SERVER_REPLY (8)

服务器发送的数据 libcurl 无法解析。在 7.51.0 之前的版本中，此错误代码为CURLE_FTP_WEIRD_SERVER_REPLY。

CURLE_REMOTE_ACCESS_DENIED (9)

我们被拒绝访问 URL 中指定的资源。对于 FTP，这种情况发生在尝试更改远程目录时。

CURLE_FTP_ACCEPT_FAILED (10)

当使用活动 FTP 会话等待服务器重新连接时，通过控制连接或类似连接发送了错误代码。

CURLE_FTP_WEIRD_PASS_REPLY (11)

将 FTP 密码发送到服务器后，libcurl 期望收到正确的回复。此错误代码表示返回了意外代码。

CURLE_FTP_ACCEPT_TIMEOUT (12)

在等待服务器连接的活动 FTP 会话期间，CURLOPT_ACCEPTTIMEOUT_MS（或内部默认值）超时已过期。

CURLE_FTP_WEIRD_PASV_REPLY (13)

libcurl 无法从服务器获取对 PASV 或 EPSV 命令的合理响应。服务器存在缺陷。

CURLE_FTP_WEIRD_227_FORMAT (14)

FTP 服务器会返回 227 行作为对 PASV 命令的响应。如果 libcurl 无法解析该行，则会传回此返回代码。

CURLE_FTP_CANT_GET_HOST (15)

查找用于新连接的主机发生内部故障。

CURLE_HTTP2 (16)

在 HTTP2 帧层检测到一个问题。这个问题比较常见，可能是多个问题之一，详情请参阅错误缓冲区。

CURLE_FTP_COULDNT_SET_TYPE (17)

尝试将传输模式设置为二进制或 ASCII 时收到错误。

CURLE_PARTIAL_FILE (18)

文件传输比预期短或长。这种情况发生在服务器首先报告预期传输大小，然后传送与先前指定大小不匹配的数据时。

CURLE_FTP_COULDNT_RETR_FILE (19)

这要么是对“RETR”命令的奇怪回复，要么是零字节传输完成。

过时的错误 (20)

在现代版本中不再使用。

CURLE_QUOTE_ERROR (21)

向远程服务器发送自定义“QUOTE”命令时，其中一个命令返回了 400 或更高（对于 FTP）的错误代码，或者表明命令未成功完成。

CURLE_HTTP_RETURNED_ERROR (22)

如果CURLOPT_FAILONERROR设置为 TRUE 并且 HTTP 服务器返回错误代码 >= 400，则返回此信息。

CURLE_WRITE_ERROR (23)

将接收的数据写入本地文件时发生错误，或者从写入回调向 libcurl 返回错误。

过时的错误 (24)

在现代版本中不再使用。

CURLE_UPLOAD_FAILED (25)

上传失败。对于 FTP 来说，服务器通常会拒绝 STOR 命令。错误缓冲区通常包含服务器对此的解释。

CURLE_READ_ERROR (26)

读取本地文件时出现问题，或者读取回调返回错误。

CURLE_OUT_OF_MEMORY (27)

内存分配请求失败。这是一个严重的问题，一旦发生，事情就会变得非常糟糕。

CURLE_OPERATION_TIMEDOUT (28)

操作超时。根据条件已达到指定的超时时间。

过时的错误 (29)

在现代版本中不再使用。

CURLE_FTP_PORT_FAILED (30)

FTP PORT 命令返回错误。这通常是因为您没有为 libcurl 指定一个足够好的地址。请参阅CURLOPT_FTPPORT。

CURLE_FTP_COULDNT_USE_REST (31)

FTP REST 命令返回错误。如果服务器正常，这种情况不应该发生。

过时的错误（32）

在现代版本中不再使用。

CURLE_RANGE_ERROR (33)

服务器不支持或接受范围请求。

过时的错误 (34)

自 7.56.0 起不再使用。

CURLE_SSL_CONNECT_ERROR (35)

SSL/TLS 握手过程中出现问题。您确实需要错误缓冲区并阅读其中的消息，因为它可以更准确地指出问题所在。问题可能涉及证书（文件格式、路径、权限）、密码等等。

CURLE_BAD_DOWNLOAD_RESUME (36)

由于指定的偏移量超出了文件边界，因此无法恢复下载。

CURLE_FILE_COULDNT_READ_FILE (37)

无法打开使用 FILE:// 指定的文件。很可能是因为文件路径没有标识现有文件。您是否检查过文件权限？

CURLE_LDAP_CANNOT_BIND (38)

LDAP 无法绑定。LDAP 绑定操作失败。

CURLE_LDAP_SEARCH_FAILED (39)

LDAP 搜索失败。

过时的错误 (40)

在现代版本中不再使用。

过时的错误 (41)

自 7.53.0 起不再使用。

CURLE_ABORTED_BY_CALLBACK (42)

回调已中止。回调向 libcurl 返回“中止”。

CURLE_BAD_FUNCTION_ARGUMENT (43)

调用函数时带有错误的参数。

过时的错误 (44)

在现代版本中不再使用。

CURLE_INTERFACE_FAILED (45)

接口错误。指定的传出接口无法使用。请使用CURLOPT_INTERFACE设置传出连接的源 IP 地址。

过时的错误 (46)

在现代版本中不再使用。

CURLE_TOO_MANY_REDIRECTS (47)

重定向次数过多。在执行重定向时，libcurl 会达到最大值。请使用CURLOPT_MAXREDIRS设置限制。

CURLE_UNKNOWN_OPTION (48)

传递给 libcurl 的选项无法识别/未知。请参阅相应文档。这很可能是使用 libcurl 的程序中存在的问题。错误缓冲区可能包含与该选项相关的更具体信息。

CURLE_SETOPT_OPTION_SYNTAX (49)

传递给 setopt 的选项格式错误。有关选项的详细信息，请参阅错误消息。

过时的错误（50-51）

在现代版本中不再使用。

卷发无所获 (52)

服务器没有返回任何内容，在这种情况下，没有得到任何内容被视为错误。

CURLE_SSL_ENGINE_NOTFOUND (53)

未找到指定的加密引擎。

CURLE_SSL_ENGINE_SETFAILED (54)

无法将选定的 SSL 加密引擎设置为默认值。

CURLE_SEND_ERROR (55)

发送网络数据失败。

CURLE_RECV_ERROR (56)

接收网络数据失败。

过时的错误 (57)

在现代版本中不再使用。

CURLE_SSL_CERTPROBLEM (58)

本地客户端证书存在问题。

CURLE_SSL_CIPHER (59)

无法使用指定的密码。

CURLE_PEER_FAILED_VERIFICATION (60)

远程服务器的 SSL 证书或 SSH 指纹被视为不正常。此错误代码自 7.62.0 起已与 CURLE_SSL_CACERT 统一。其先前值为 51。

CURLE_BAD_CONTENT_ENCODING (61)

无法识别的传输编码。

过时的错误（62）

在现代版本中不再使用。

CURLE_FILESIZE_EXCEEDED (63)

超出最大文件大小。

CURLE_USE_SSL_FAILED (64)

请求的 FTP SSL 级别失败。

CURLE_SEND_FAIL_REWIND (65)

在执行发送操作时，curl 必须倒回数据以重新传输，但倒回操作失败。

CURLE_SSL_ENGINE_INITFAILED (66)

启动 SSL 引擎失败。

CURLE_LOGIN_DENIED (67)

远程服务器拒绝 curl 登录（7.13.1 新增）

CURLE_TFTP_NOTFOUND (68)

TFTP 服务器上未找到文件。

CURLE_TFTP_PERM (69)

TFTP 服务器的权限问题。

CURLE_REMOTE_DISK_FULL (70)

服务器磁盘空间不足。

CURLE_TFTP_ILLEGAL (71)

非法 TFTP 操作。

CURLE_TFTP_UNKNOWNID (72)

未知的 TFTP 传输 ID。

CURLE_REMOTE_FILE_EXISTS (73)

文件已存在且未被覆盖。

CURLE_TFTP_NOSUCHUSER (74)

正常运行的 TFTP 服务器绝不会返回此错误。

过时的错误（75-76）

在现代版本中不再使用。

CURLE_SSL_CACERT_BADFILE (77)

读取 SSL CA 证书时出现问题（路径？访问权限？）

CURLE_REMOTE_FILE_NOT_FOUND (78)

URL 中引用的资源不存在。

CURLE_SSH (79)

SSH 会话期间发生未指定的错误。

CURLE_SSL_SHUTDOWN_FAILED (80)

无法关闭 SSL 连接。

再次卷曲 (81)

套接字尚未准备好发送/接收。请等待其准备就绪后重试。此返回码仅由curl_easy_recv和curl_easy_send返回（已在 7.18.2 版本中新增）。

CURLE_SSL_CRL_BADFILE (82)

无法加载 CRL 文件（7.19.0 版新增）

CURLE_SSL_ISSUER_ERROR (83)

发卡机构检查失败（7.19.0 版新增）

CURLE_FTP_PRET_FAILED (84)

FTP 服务器完全无法理解 PRET 命令，或者不支持指定的参数。使用CURLOPT_CUSTOMREQUEST时请务必小心，因为自定义的 LIST 命令也会在 PASV 之前随 PRET 命令一起发送。（7.20.0 新增）

CURLE_RTSP_CSEQ_ERROR (85)

RTSP CSeq 编号不匹配。

CURLE_RTSP_SESSION_ERROR (86)

RTSP 会话标识符不匹配。

CURLE_FTP_BAD_FILE_LIST (87)

无法解析 FTP 文件列表（在 FTP 通配符下载期间）。

CURLE_CHUNK_FAILED (88)

Chunk回调报告错误。

CURLE_NO_CONNECTION_AVAILABLE (89)

（仅供内部使用，libcurl 永远不会返回）无可用连接，会话已排队。（在 7.30.0 中添加）

CURLE_SSL_PINNEDPUBKEYNOTMATCH (90)

无法匹配使用CURLOPT_PINNEDPUBLICKEY指定的固定密钥。

CURLE_SSL_INVALIDCERTSTATUS (91)

当使用CURLOPT_SSL_VERIFYSTATUS询问时，状态返回失败。

CURLE_HTTP2_STREAM (92)

HTTP/2 框架层中的流错误。

CURLE_RECURSIVE_API_CALL (93)

从回调内部调用了 API 函数。

CURLE_AUTH_ERROR (94)

身份验证函数返回错误。

CURLE_HTTP3 (95)

HTTP/3 层检测到一个问题。这个问题比较常见，可能是多个问题之一，详情请参阅错误缓冲区。

CURLE_QUIC_CONNECT_ERROR (96)

QUIC 连接错误。此错误可能是由 SSL 库错误引起的。QUIC 是用于 HTTP/3 传输的协议。

CURLE_PROXY (97)

代理握手错误。CURLINFO_PROXY_ERROR提供有关具体问题的额外详细信息。

CURLE_SSL_CLIENTCERT (98)

需要 SSL 客户端证书。

CURLE_UNRECOVERABLE_POLL (99)

对 poll() 或 select() 的内部调用返回了无法恢复的错误。

卷曲过大 (100)

值或数据字段超出了允许值。

CURLE_ECH_REQUIRED (101)

尝试过 ECH 但失败了。

Curlmcode

这是 libcurl 多接口函数使用的通用返回码。另请考虑curl_multi_strerror。

CURLM_CALL_MULTI_PERFORM (-1)

这实际上并非错误。这意味着您应该再次调用curl_multi_perform ，并且不要在调用期间执行 select() 或类似操作。在 7.20.0 版本（发布于 2010 年 2 月 9 日）之前， curl_multi_perform可能会返回此错误代码，但在更高版本中，此返回代码不再使用。

CURLM_OK (0)

一切都很好。

CURLM_BAD_HANDLE (1)

传入的句柄不是有效的CURLM句柄。

CURLM_BAD_EASY_HANDLE (2)

简易句柄无效/无效。这可能意味着它根本不是简易句柄，或者该句柄已被此句柄或其他多句柄使用。

CURLM_OUT_OF_MEMORY (3)

你完了。

CURLM_INTERNAL_ERROR (4)

仅当 libcurl 出现错误时才会返回此信息。请向我们报告。

CURLM_BAD_SOCKET (5)

传入的套接字不是 libcurl 已知的有效套接字。（在 7.15.4 中添加）

CURLM_UNKNOWN_OPTION (6)

curl_multi_setopt() 带有不受支持的选项（在 7.15.4 中添加）

CURLM_ADDED_ALREADY (7)

已添加到多句柄的简易句柄被尝试再次添加。（已在 7.32.1 版中添加）

CURLM_RECURSIVE_API_CALL (8)

从回调内部调用了 API 函数。

CURLM_WAKEUP_FAILURE (9)

唤醒不可用或失败。

CURLM_BAD_FUNCTION_ARGUMENT (10)

调用函数时带有错误的参数。

CURLM_ABORTED_BY_CALLBACK (11)

多句柄回调返回错误。

CURLM_UNRECOVERABLE_POLL (12)

对 poll() 或 select() 的内部调用返回了无法恢复的错误。

Curlsh代码

“share” 接口会返回一个CURLSHcode来指示错误发生的时间。另请考虑curl_share_strerror。

CURLSHE_OK (0)

一切顺利。一切照常进行。

CURLSHE_BAD_OPTION (1)

向函数传递了无效选项。

CURLSHE_IN_USE (2)

共享对象当前正在使用中。

CURLSHE_INVALID (3)

无效的共享对象被传递给了该函数。

CURLSHE_NOMEM (4)

可用内存不足。（7.12.0 新增）

CURLSHE_NOT_BUILT_IN (5)

无法执行请求的共享，因为您使用的库未启用该特定功能。（7.23.0 新增）

Curlucode

URL 接口会返回一个CURLUcode来指示错误发生的时间。另请考虑curl_url_strerror。

CURLUE_OK (0)

一切顺利。一切照常进行。

CURLUE_BAD_HANDLE (1)

传递了一个无效的 URL 句柄作为参数。

CURLUE_BAD_PARTPOINTER (2)

无效的“部分”参数作为参数传递。

CURLUE_MALFORMED_INPUT (3)

格式错误的输入被传递给 URL API 函数。

CURLUE_BAD_PORT_NUMBER (4)

端口号不是 0 至 65535 之间的十进制数。

CURLUE_UNSUPPORTED_SCHEME (5)

此 libcurl 构建不支持给定的 URL 方案。

CURLUE_URLDECODE (6)

URL 解码错误，很可能是因为输入内容混乱。

CURLUE_内存不足 (7)

记忆功能失败。

CURLUE_USER_NOT_ALLOWED (8)

禁止时，凭据已在 URL 中传递。

CURLUE_UNKNOWN_PART (9)

未知的部件 ID 被传递给 URL API 函数。

CURLUE_NO_SCHEME (10)

URL 中没有方案部分。

CURLUE_NO_USER (11)

URL 中没有用户部分。

CURLUE_无密码 (12)

URL 中没有密码部分。

CURLUE_NO_OPTIONS (13)

URL 中没有选项部分。

CURLUE_NO_HOST (14)

URL 中没有主机部分。

CURLUE_NO_PORT (15)

URL 中没有端口部分。

CURLUE_NO_QUERY (16)

URL 中没有查询部分。

CURLUE_NO_FRAGMENT (17)

URL 中没有片段部分。

CURLUE_NO_ZONEID (18)

URL 中未设置区域 ID。

CURLUE_BAD_FILE_URL (19)

file:// URL 无效。

CURLUE_BAD_FRAGMENT (20)

URL 的片段部分包含错误或无效的字符。

CURLUE_BAD_HOSTNAME (21)

主机名包含错误或无效的字符。

CURLUE_BAD_IPV6 (22)

IPv6 地址主机名包含错误或无效的字符。

CURLUE_BAD_LOGIN (23)

URL 的登录部分包含错误或无效的字符。

CURLUE_BAD_PASSWORD (24)

URL 的密码部分包含错误或无效的字符。

CURLUE_BAD_PATH (25)

URL 的路径部分包含错误或无效的字符。

CURLUE_BAD_QUERY (26)

URL 的查询部分包含错误或无效的字符。

CURLUE_BAD_SCHEME (27)

URL 的方案部分包含错误或无效的字符。

CURLUE_BAD_SLASHES (28)

URL 包含无效数量的斜杠。

CURLUE_BAD_USER (29)

URL 的用户部分包含错误或无效的字符。

CURLUE_LACKS_IDN (30)

libcurl 缺乏 IDN 支持。

卷发过大 (31)

值或数据字段大于允许值。

Curlhcode

标头接口返回一个CURLHcode来指示何时发生错误。

CURLHE_OK (0)

一切顺利。一切照常进行。

CURLHE_BADINDEX (1)

没有具有请求索引的标题。

CURLHE_MISSING (2)

不存在这样的标题。

CURLHE_NOHEADERS (3)

根本没有记录任何标题。

CURLHE_NOREQUEST (4)

没有此请求编号。

CURLHE_OUT_OF_MEMORY (5)

资源不足

CURLHE_BAD_ARGUMENT (6)

给定的一个或多个参数不正确。

CURLHE_NOT_BUILT_IN (7)

HTTP 支持或标头 API 已在构建中被禁用。