如何在调用 CAPTCHA API 时修复 ERROR_TASK_NOT_SUPPORTED 错误

摘要

• ERROR_TASK_NOT_SUPPORTED 表示提交的验证码类型不正确，或当前服务不支持该类型。
• 要查看实际通过网络发送的 task.type，而不是只看框架配置中展示的标签。
• 将当前验证码家族和变体与官方任务参考中的精确类型一一对应。
• REST 任务类型、SDK 检测名称和 MCP 工具名称属于不同接口，不能互换使用。
• 在重试之前先修正不兼容的请求；对同一个错误请求反复提交并不会让该任务变成受支持。

验证码集成有可能在识别开始之前就失败。API 收到请求后，会检查其中的任务类型，并拒绝执行不支持的操作。在这种情况下，更换站点公钥、等待更久或增加重试次数，都可能对真正的问题毫无帮助。

CapSolver 将 ERROR_TASK_NOT_SUPPORTED 与无效任务数据和识别失败分开记录。有效的排错路径是：比较你的应用实际发送的请求，与所用服务和集成接口的契约是否一致。

ERROR_TASK_NOT_SUPPORTED 告诉你的是什么

ERROR_TASK_NOT_SUPPORTED 标识的是任务类型兼容性问题；它并不能说明验证码图片很难，或返回的 token 已过期。

官方错误码参考 将这一情况定义为验证码类型错误或不受支持。排查失败时要保留 errorCode 和 errorDescription。如果应用只报“solver 失败”之类的泛化信息，就丢失了选择修复方案所需的关键差异。

先弄清三点事实：哪个 endpoint 收到了请求，它收到的具体类型字符串是什么，以及页面上实际存在的是哪一类验证码。这是用来对照文档和实现的最小信息集。

API 参数 是服务契约的一部分。名字看起来“像那么回事”并不代表就是受支持的名字。大小写、拼写、后缀以及家族特定的变体，都应以官方参考为准，而不是凭其它服务商推断的命名模式。

第 1 步：检查已序列化的请求

在 SDK、配置层或中间件完成转换之后，再检查发出的请求。

设置界面也许写着“reCAPTCHA v2”，而最终 JSON 内却是另一字符串。环境变量里可能仍然保留着已废弃的值。包装库可能将一个“友好名称”映射成已不再匹配当前服务的任务标识。要读的是生效值，而不能想当然地以为初始配置原封不动地到了 API。

在浏览器端客户端中，可以参考 Chrome Network 面板 来检查请求与响应。对服务端代码来说，应使用作用范围尽可能窄、并去除敏感信息的诊断日志。避免记录 API key、会话 cookie、完整 token 或无关表单数据。

记录方法、目标主机和路径、任务类型、字段名，以及响应中的错误码和描述。只有在服务确实返回了任务 ID 时才记录它。如果任务在创建阶段就失败，你可能根本拿不到可用的 ID 供后续轮询。

单独检查 JSON 结构

合法的 JSON 语法并不代表任务就是受支持的。JSON 规范 描述的是数据格式；API 参考则定义了字段所允许的语义。

当验证器说请求“结构良好”但 API 仍然拒绝时，这个区分就很有用：语法正确的字符串依然可能指向一个不受支持的操作。反过来，数据格式错误也应当单独诊断，而不是被当作同一个错误来看待。

第 2 步：将当前挑战与其官方任务对应起来

在选择替代任务类型之前，先确认当前验证码的家族和变体。

使用 任务类型总览 找到正确的家族，然后打开该家族的详细参考。例如，reCAPTCHA v2 任务参考 列出了可接受的 v2 任务名称及其字段。请从相应条目中直接复制标识符，而不要凭记忆“拼”出来。

如果应用最近改过验证码集成，再次检查真实页面。历史配置里描述的可能是之前的服务商或变体。仅凭控件的外观，并不足以证明旧任务类型仍然适用。

同时检查“token 任务”和“识别任务”之间的边界。前者可能为应用流转返回 token，而后者则回答图像识别请求。仅因二者都与验证码相关，就把它们当成可以互换的操作，会导致错误的请求契约。

不要“随便试一堆”任务名称，直到某个被接受为止。这会掩盖原始故障原因，还可能触发与你应用实际需求完全不同的操作。

兑换你的 CapSolver 优惠码

立即提升你的自动化预算！
在为 CapSolver 账户充值时使用优惠码 CAP26，每次充值都可额外获得 5% 奖励——无次数上限。
现在就到你的 CapSolver 控制面板 中兑换。

第 3 步：将 REST、SDK 和 MCP 的名称各自隔离

让每个集成接口只在定义它的范围内使用其名称。

REST 请求发送的是任务对象。SDK 可能暴露方法和标准化的检测值。MCP 客户端则调用具备自身输入模式的工具。某一层返回的名称，并不会自动成为另一层有效的 task.type。

例如，Core SDK 参考 说明了其浏览器和解题方法。使用该 SDK 时，要遵循其文档中的参数说明。直接构造 REST 请求时，则要使用 REST 的任务参考。使用 MCP 时，要检查工具自身的 schema，而不是把工具名塞进 REST 任务字段中。

在迁移过程中，这一点尤为重要。替换软件包或更改 API host 后，可能仍然残留旧的配置值。即便响应格式大体类似，不同服务也可能采用不同的任务标识和可选字段。必须显式比较来源和目标的契约。

在服务商尚未文档化支持路径之前，不受支持的功能就应当视为“不受支持”。不要悄悄替换成不同的验证码家族，只为让请求通过验证。

第 4 步：修正单个请求后再恢复队列

在让同一配置流向所有 worker 之前，先验证一个已修正的请求。

首先停止对已知不兼容请求的自动重复发送。然后只修改已定位到的不匹配问题，进行一次范围受控的测试。查看返回状态和字段，再决定是否恢复更大范围的工作流。

当网络故障导致操作结果不确定时，HTTP 关于重试非幂等请求的建议 就很相关。不要想当然地把“新建任务请求”当作“获取已有任务结果”的等价物。兼容性错误与传输不确定性需要截然不同的处理方式。

如果修正后的请求被接受，就按该任务文档中描述的响应流程继续。有的操作会直接返回结果；有的则需要再发起结果获取请求。不要凭空编造任务 ID 或开始轮询，只因为你之前的集成总是这样做。

对于持续的“请求压力”问题，请参考单独的 验证码 API 故障排查参考 来识别实际返回的状态。任务类型不受支持、速率限制和账号错误并不是同一个失败的不同叫法。

若类型看上去没问题，该向支持团队提供什么

向支持团队提供一个精简、脱敏的复现，展示看似契约不匹配的情况。

包括你参考的文档 URL、精确的任务类型、调用的 endpoint，如使用了 SDK 或包装库，还要包含其版本号，以及完整的错误码和描述。再附上请求时间及其时区，如有可用的任务 ID 也一并附上。

说明发生了什么变化：软件包升级、服务商迁移、新的验证码家族，或部署配置修改。这比整份应用日志能为支持人员提供更聚焦的起点。

不要默认发送账号密钥或完整的已认证浏览器抓包。目标是展示“不受支持的操作”和相关请求结构。如果需要更多证据，再通过相应的支持流程提供。

现有的不可解错误指南 针对的是另一阶段：任务已被识别，但这一次尝试未能产出解决方案。只有在你实际收到的是那个错误时才使用该指南。

使用 CapSolver 构建可靠的自动化工作流

先修复任务契约，然后在受控范围内测试请求并检查其结果。CapSolver 当前的任务参考应当作为受支持名称和必填字段的唯一来源。保持这些名称的显式和清晰，有助于迁移与支持调查的审查。

常见问题

问：重试能修复 ERROR_TASK_NOT_SUPPORTED 吗？

在不做任何修改的前提下重试，并不能修复一个不受支持或错误的任务类型。重新提交前，请先检查契约以及实际发出的请求。

问：这和 ERROR_CAPTCHA_UNSOLVABLE 是同一个错误吗？

不是。不受支持任务错误关注的是所请求的任务类型；不可解错误关注的是一次未能识别验证码的尝试。在选择修复方案前，请先阅读具体的响应内容。

问：可以把 SDK 的检测名称当作 task.type 使用吗？

只有在 REST 参考明确列出该值时才可以。检测标签、SDK 方法名和 MCP 工具名是不同接口层面的概念。

问：为什么换了服务商之后才出现这个错误？

更换服务商可能遗留属于前一服务的任务标识或映射。请对比最终序列化请求与目标服务商当前的参考文档。

问：我应该先改 sitekey 吗？

不要下意识就改。先确认任务类型是否受支持，然后再根据文档契约校验家族特定字段，包括页面 URL 和 sitekey。