solvethree API 错误：应修复什么，何时重试

读取成功响应体之前，请先处理非成功的 HTTP 响应。对于 POST /v1/tasks，201 表示已创建新任务；200 表示幂等重放返回了现有任务。这两种响应都不表示解题已完成。

400 — 请求体无效

将提交的请求体与文档中对应任务类型的字段和要求进行对照。

试试这样做： 再次提交前请修正输入。原样重试无效的请求体无法解决问题。请根据任务创建规范检查请求。

401 — API 密钥无效

检查请求是否包含 Authorization: Bearer，且后接有效的工作区 API 密钥。

试试这样做： 添加缺失的密钥或修正被拒绝的密钥。请将其保存在服务器端，不要在浏览器代码中暴露。

402 — 余额不足

检查与该 API 密钥关联的工作区余额。

试试这样做： 重试前请为该工作区充值。不要将无关的 HTTP 错误或任务失败视为余额问题。

403 — 站点配置未激活

对于 reCAPTCHA，请确认目标站点具有已激活且可供你的工作区使用的配置。

试试这样做： 在控制台中设置目标站点，并确认配置已激活。在任务中提供主机名和 action 并不会创建配置。此网关响应并不能证明目标网站封锁了你。

409 — 请求 ID 冲突

检查之前是否曾将相同的 requestId 用于不同的任务输入。

试试这样做： 使用原始输入恢复原始任务。如果要创建不同的任务，请为其分配新的请求 ID。

410 — 已存储的结果已过期

检查你是否正在获取一个已完成、但其存储结果已不再保留的任务。

试试这样做： 停止获取该结果。如果仍有需要，请创建新的解题任务。此状态描述的是 API 结果保留情况，而非目标令牌或 Cookie 的有效期。

429 — 请求受到速率限制

读取实际返回的 Retry-After 响应。

试试这样做： 按指示等待后再重试，并降低请求速率。受到限流时，不要继续以相同速率轮询或提交请求。

502 — 生成服务不可用

区分服务不可用、输入无效和余额不足这几种情况。

试试这样做： 稍后重试。如果重试同一个创建请求，请复用其请求 ID，并保持任务输入不变。

HTTP 503 表示当前无可用的生成容量。请稍后重试；对于同一个创建请求，请复用其请求 ID，并保持任务输入不变。

• pending 或 solving：继续轮询现有任务；不要仅因任务尚未就绪就创建替代任务。
• ready：停止轮询并读取解决结果。
• failed：停止轮询并检查 errorCode 和 error。

{
  "id": "example_login_001",
  "status": "failed",
  "errorCode": "site-unreachable",
  "error": "target page did not respond"
}

这里的 site-unreachable 是任务错误码，而非 HTTP 状态。请求再次解题前，请检查提交的目标 URL 以及页面是否响应。增加轮询次数不会重启这个失败任务，重放其原始请求 ID 也只会返回现有任务，而不会启动替代任务。

连接超时并不能证明任务创建失败。在首次尝试创建前使用可选的 requestId，即可安全地恢复同一个逻辑任务。它必须包含 1–64 个 ASCII 字母、数字、下划线或连字符。

1. 1.

   如果已有任务 ID，直接获取任务

   使用 GET /v1/tasks/:id，并在检查任务状态前处理 HTTP 响应。

2. 2.

   如果创建响应丢失，重放原始请求

   使用相同的请求 ID 提交相同的任务输入。如果任务已创建，幂等重放会返回现有任务。不要在该 ID 下更改输入。

3. 3.

   仅在确实要开始另一次解题时创建替代任务

   新的请求 ID 代表新任务，而不是恢复先前的请求。请有意识地使用它，例如，在调查终态失败原因并决定重试之后。

有关重放处理，请参阅请求 ID 恢复；如果创建成功但任务仍在运行，请参阅轮询与超时。