Polymarket API 错误：每个错误码逐一解读

每个 Polymarket CLOB API 错误返回的格式都一样：一个只有 error 字段的 JSON 对象。这种一致性值得称赞，但当你想弄清楚自己的订单为什么凭空消失时，它毫无帮助。

{
  "error": "<message>"
}

本页负责解读它们。内容包括有文档的 CLOB 错误、状态码及其真实原因，以及官方文档里找不到的部分：人们在生产环境中实际遇到、而 Polymarket 从未写下来的错误。

每条有文档的消息也都有自己的页面，介绍原因和是否应重试，列在 Polymarket 错误索引中。

状态码速查

401：认证错误

Unauthorized/Invalid api key

被搜索最多的 Polymarket 错误。你的 API 密钥缺失、过期或无效。实际上它几乎从来不是密钥真的有问题，而是以下情况之一：

1. 你只发送了部分凭证。Polymarket 的 L2 认证需要 key、secret 和 passphrase 三者一起。常见的失败是设置了 POLY_API_KEY 和 POLY_PASSPHRASE，却没设置 secret：客户端发送了一个格式正确但无法签名的请求。
2. 你的系统时钟发生了漂移。签名中包含时间戳，时钟偏差超过几秒，产生的签名就会被服务器判定为无效。这是人们最后才找到的原因，而在虚拟机和容器上它常见得令人沮丧。
3. 你派生密钥所用的钱包与你交易所用的钱包不同。密钥与创建它的签名者地址绑定。
4. 你在需要 L2 的认证端点上使用了 L1 请求头，或者反过来。

Invalid L1 Request headers

你的 L1 认证请求头（EIP-712 签名组）格式错误，或者签名与你声称的地址不匹配。检查你签名用的私钥是否与请求头中的地址一致，以及你的域分隔符是否与所在的链匹配（Polygon，链 ID 137）。对错误链 ID 有效的签名仍然是有效签名，只是对这个服务器无效。

Could not create api key / Could not derive api key!

这些就是“polymarket unable to generate api credentials”这类搜索背后的错误。两者都是在创建或派生密钥失败时由认证端点返回的。GET /auth/derive-api-key 返回 Could not derive api key! 通常意味着该签名者还没有密钥：derive 返回的是已有的密钥，它不会创建新密钥。先用 POST /auth/api-key 创建密钥，之后运行时再派生。

400：订单拒绝错误

当一个订单通过了传输层校验但违反了业务规则时，会返回这些错误。它们出现在 POST /order 和 POST /orders 的响应主体中。

425：Too Early

这是一个不常见的状态码，因为在网络上的其他地方很少用到，所以容易让人困惑。在 Polymarket 上，它意味着撮合引擎正在重启。你的请求恰好在交易所恢复的窗口期到达。

这个错误是真正暂时性的，也真正可以安全重试，可以说是平台上最适合重试的错误。退避后再试；不要把它当作失败，也不要对单次出现发出告警。

503：交易所处于受限模式

Polymarket 可以让交易所进入受限模式。这些不是你这一侧的故障，在模式解除之前，重试多少次相同的请求都没用。

仅挂单模式是需要妥善处理的那一个，因为它会准确告诉你什么时候再来。响应中包含 code: "post_only_mode" 和 retry_after_seconds，同样的延迟也会在 Retry-After 响应头中发送。

{
  "error": "post-only mode: only post-only orders and cancels are allowed",
  "code": "post_only_mode",
  "retry_after_seconds": 79
}

文档里没有的错误

大部分真实的调试时间都花在这里。下面这些没有出现在 Polymarket 的错误码参考中，因为它们根本不是来自 CLOB 应用：它们来自边缘层、网络或你的客户端库。知道是哪一层产生了错误，你就知道该去哪里找。

“The server was unable to process your request”

文档中没有、却被搜索最多的 Polymarket 错误。这是一条边缘层消息，而不是 CLOB API 错误：当请求从未到达应用，或者从未从应用干净地返回时，你就会收到它。实际中常见的原因是：

• 边缘层在路由之前就拒绝了格式错误的请求：载荷过大、请求头有误，或者该路由不支持的 HTTP 方法。
• 服务重新部署或负载较高时的暂时性上游故障。
• 持续被限流。由于 Cloudflare 是通过排队而不是拒绝来限流的，严重超出限制的客户端，请求可能会在边缘层超时，而不是返回一个干净的 429。

把它当作可带退避重试的错误，但如果它是持续出现而不是偶尔出现，先检查你的请求速率（见速率限制参考），再检查你的载荷大小。

403 Forbidden

来自 Polymarket 的 403 通常不是认证问题，这正是它让人困惑的地方。它一般是边缘层在拦截请求。常见的触发原因包括：交易端点的地域限制、数据中心和 VPN 的 IP 段被质询，以及边缘层期望来自客户端的请求缺少请求头或请求头不像浏览器。

如果 403 只在你的云虚拟机上出现，而在你的笔记本上不出现，那是 IP 信誉问题，而不是代码问题。如果它出现在交易端点而不出现在市场数据端点，那是地域问题。

SSL、TLS 和证书错误

“polymarket ssl error”、“polymarket certificate error” 和 “polymarket https error” 几乎总是客户端的问题。Polymarket 的证书没有问题；有问题的是你和它们之间的某个环节。按顺序检查：过时的 CA 证书包（在旧的 Docker 镜像和冻结的 Python 环境中非常常见）、替换成自己证书的企业 TLS 检查代理，以及偏差大到让证书看起来尚未生效或已过期的系统时钟。

# 1. Does TLS work at all, outside your app's HTTP client?
curl -sS -o /dev/null -w "%{http_code} %{ssl_verify_result}\n" \
  https://clob.polymarket.com/ok

# 2. Is your CA bundle current? (Python)
python3 -c "import certifi, os; print(certifi.where()); print(os.path.getmtime(certifi.where()))"

# 3. Is your clock right? Certificate validation depends on it.
date -u

“Service not ready”

一条启动状态消息：服务已经能应答，但还不能提供服务。在功能上把它当作 425 处理：退避并重试。它应该在几秒内消失，而且你无法从客户端修复它。

“Order manager not ready”

一条来自撮合引擎的启动状态消息，与 425 Too Early 是近亲。服务可以访问，但订单管理层还没有完全启动，所以它会接受你的连接，却拒绝你的订单。它是暂时性的，可以安全地带退避重试；但要把它当作暂停提交几秒的信号，而不是猛烈重试，因为重启通常意味着订单簿即将在你脚下变化。

如果它持续出现而不是阵发性出现，在调试你自己的代码之前先查看 Polymarket 的状态：客户端没有什么可修的。

“Couldn't get a quote”

通常意味着你请求定价的那一方没有挂单流动性，而不是有什么东西坏了。在临近到期、流动性很薄的 Up/Down 市场上，一方经常会被清空：一旦 Up 已成定局，就没人会以任何价格卖出 Up，所以报价请求什么都返回不了。我们自己的数据表明这种情况很常见：在一组 BTC 5 分钟市场样本中，8,510 个中有 1,454 个在到期前 60 秒有一方的卖单簿为空。

把它当作“没有市场”而不是错误来处理：跳过这笔交易，不要在紧密循环中重试。如果你需要知道你交易的某个系列中这种情况发生得有多频繁，市场数据页面按时间周期展示了流动性。

客户端库异常

像 PolyApiException[status_code=None, error_message=request exception!] 这样的错误来自 Python 客户端，而不是服务器。status_code=None 是关键线索：从未收到任何 HTTP 响应，所以这是连接层面的失败（DNS、TLS、超时或 socket 断开），以库异常的形式表现出来。把它当作网络问题来调试，而不是 API 问题。同样的思路也适用于 relayer 客户端中的 BuilderApiKeyCreds invalid authorization 401，它意味着传给客户端的 builder 凭证没有被接受；请重新派生，而不是复用缓存的那一套。

一套能处理以上所有情况的重试策略

实际的结论是，Polymarket 的错误分为三类，而把它们混为一谈正是机器人脆弱的原因：直接重试、在特定延迟后重试，以及永不重试。

type Decision =
  | { retry: true; delayMs: number }
  | { retry: false; reason: string };

function classify(status: number, body: { error?: string; code?: string; retry_after_seconds?: number }, attempt: number): Decision {
  const msg = (body.error ?? "").toLowerCase();
  const backoff = Math.min(2 ** attempt * 250, 8000);
  const jittered = Math.random() * backoff;

  // Never retry — the request itself is wrong.
  if (status === 401) return { retry: false, reason: "auth: check key, secret, passphrase and clock drift" };
  if (status === 404) return { retry: false, reason: "not found" };
  if (status === 400) return { retry: false, reason: `validation: ${body.error}` };

  // Mode-restricted — the server tells you when to come back.
  if (status === 503 && body.code === "post_only_mode") {
    return { retry: true, delayMs: (body.retry_after_seconds ?? 60) * 1000 };
  }
  if (status === 503) return { retry: false, reason: "exchange paused or cancel-only" };

  // Transient — safe to retry.
  if (status === 425 || status === 429 || status >= 500) return { retry: true, delayMs: jittered };
  if (msg.includes("service not ready")) return { retry: true, delayMs: jittered };

  return { retry: false, reason: `unhandled status ${status}` };
}

靠调试解决不了的错误

有些看起来像错误的东西，其实只是不受支持。Polymarket 没有历史订单簿端点，所以根本不存在调用方式错误的问题。已结算市场的订单簿返回 404，是因为市场结算后 Polymarket 就不再提供它，即使你的代币 ID 完全正确。

如果你撞上了这些墙，你不是在调试一个集成，而是缺少一个数据源。PolyTest 在 Polymarket 加密货币 Up/Down 市场运行期间记录时点快照，带完整订单簿深度，所以结算后历史数据依然存在。我们自己的错误参考介绍了 PolyTest API 的错误格式，相比之下它们刻意设计得很无聊。