Polymarket 错误代码与修复

本指南解释在 UI 和 API 中最常见的 Polymarket 错误代码、它们发生的原因，以及可执行的解决步骤。如果你在调试集成、下单流程或钱包连接，本指南能帮助你快速排查问题。

要点摘要

• Polymarket 错误通常落入几个类别：地理封锁（403）、API 验证（422）、速率限制、CLOB/交易认证、钱包或 pUSD 资金问题，以及 CTF 操作相关故障。
• 对于 Gamma 的列表调用，使用基于游标的分页（after_cursor）——offset 会被 HTTP 422 拒绝。
• CLOB 的交易需要 API key + HMAC；读取操作是公开的。
• 许多 UI 层面的“订单被拒绝”是由钱包部署、pUSD 不足、授权、tick-size 变更或 FAK 部分成交 导致的——检查 Relayer 流程和 CLOB 的订单响应。

为什么错误很重要（简要）

在预测市场流程中，错误会阻止下单、导致部分成交或中断对账。Polymarket 使用多个服务面（Gamma、Data、CLOB 和 Market WebSocket）。知道哪个面抛出错误可以缩小修复范围。

H2: 常见的 API 和 WebSocket 错误模式

Gamma (https://gamma-api.polymarket.com)

• 症状：使用 offset 对 markets 分页时出现 HTTP 422。
  • 原因：Gamma 使用键集分页（keyset pagination）。offset 被拒绝。
  • 修复：使用上一调用返回的 next_cursor 对应的 after_cursor。示例：

curl 'https://gamma-api.polymarket.com/markets?limit=100&after_cursor=eyJpZCI6Ij...' \
  -H 'Accept: application/json'

• 症状：在高负载下出现类似 429 的限流行为或不可预期的 5xx。
  • 原因：Gamma 对端点实施了特定速率限制（例如 /markets 有单独限额）。
  • 修复：遵守文档中列出的限制，使用指数退避重试，并合并请求（在合适时将 limit 提高到最大 1000）。

Data API (https://data-api.polymarket.com)

• 读取持仓、交易和未平仓量等常见请求是公开的；如果看到认证失败，请核实基础 URL 与请求头是否正确。

CLOB (https://clob.polymarket.com)

• 症状：在访问交易端点下单时出现认证错误导致下单被拒。
  • 原因：交易端点需要 API key 和 HMAC 签名。读取（订单簿、midpoint、价格历史）是公开的。
  • 修复：按照 CLOB 规范生成并签名请求；先测试读取接口再尝试写入。

Market WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market)

• 症状：连接被关闭或没有实时事件。
  • 原因：该 socket 期望每 10 s 有一次 PING；服务器可能会断开空闲连接。此外，每个连接最多可订阅 500 个标的。
  • 修复：按要求发送 PING，并在超过 500 个标的时拆分订阅到多个连接。

H2: 地理封锁与 HTTP 403（Polymarket geoblock 403）

• 症状：尝试下单或访问交易路径时出现 HTTP 403；UI 返回地理封锁信息。
  • 原因：Polymarket 按 IP 阻止某些司法辖区的下单。一些地区被完全封锁，少数为只允许平仓。
  • 修复：确认你的 IP 位置。如果你处于被封锁地区，请遵循 Polymarket 官方关于资格的指引。不要尝试使用 VPN 绕过——这会违反服务条款。如果你认为封锁是错误，请通过官网联系 Polymarket 支持并提供连接诊断和 IP 证据。

H2: 常见的“订单被拒绝”原因及修复

1. 钱包尚未部署或代理缺失

• 症状：在 Relayer 流程中下单失败并出现部署或代理错误。
• 原因：Polymarket 支持两种钱包类型；非 Safe 用户在第一次交易时会自动部署一个 proxy。
• 修复：让 Relayer 完成钱包部署流程。交易完成后重试下单。

2. pUSD 或代币余额不足

• 症状：订单因余额不足被拒绝。
• 原因：交易需要 pUSD。
• 修复：为账户充值 pUSD（参见 Polymarket 指南）。确认钱包中的代币合约与余额。

3. ERC-20 授权与 Relayer 流程

• 症状：下单尝试在等待授权时挂起。
• 原因：Relayer 可以无 gas 地处理授权，但钱包流程必须完成。
• 修复：确认 Relayer 请求已完成，并在钱包 UI 中检查是否有待处理的确认。

4. Tick-size 与最小增量失败

• 症状：订单被拒或被意外四舍五入；较小的价格差异无法被接受。
• 原因：Polymarket 强制执行 tick size（通常为 $0.01，在极端接近 0 或 1 时收紧到 $0.001）。
• 修复：将价格和数量按当前 tick 四舍五入。通过 Market WebSocket 订阅 tick_size_change 以检测变更。

5. FAK / 市价单部分成交与滑点

• 症状：市价单返回部分成交或看似被取消。
• 原因：CLOB helper 使用 FAK（Fill-And-Kill）。如果未能在滑点保护范围内完全匹配，剩余订单会被取消。
• 修复：检查 createMarketOrder 的响应以获取已成交数量，并在程序中处理部分成交逻辑。

6. 与费用或类别相关的拒绝

• 症状：订单因费用相关错误失败。
• 原因：Taker 费用按市场类别不同（当前在 0%–1.8% 范围）；Builder 可能会加收额外基点。
• 修复：确认市场类别以及在使用 Builder 时的归属头（attribution headers）。确保你的成本计算包含 taker 费用。

H2: CTF 操作与结算错误

• 症状：split/merge/redeem 操作失败或返回错误。
• 原因：CTF 是 ERC-1155 的结果代币框架；如果你缺乏 pUSD、代币，或预言机的解析存在争议，操作可能失败。
• 修复：核实余额并确认 UMA 的解析已完成。如果 UMA 的争议暂停了结算，请等待 UMA 最终裁定。

H2: 故障排查清单（快速运行手册）

• 确认哪个服务面报告了错误（Gamma、Data、CLOB 或 WebSocket）。
• 在尝试写入前，复现最小的失败请求（GET 订单簿或 GET 市场）。
• 检查钱包状态：proxy 是否已部署、pUSD 余额、是否有待处理的 Relayer 交易。
• 验证 tick size 并据此四舍五入输入。
• 对于分页错误，切换到 after_cursor（Gamma）。
• 遵守速率限制并在遇到 429/5xx 时退避重试。

这如何影响你的交易或集成

阻塞订单的错误会增加延迟并影响执行质量。构建防御性客户端逻辑：检测部分成交、向用户展示清晰的错误信息，并持久化足够的状态以实现安全重试。对于通过 CLOB 路由订单的 builders，确保你的归属头和 API key/HMAC 正确，以避免意外的拒绝。

结语

Polymarket 的错误代码通常指向少数根本原因：地理封锁、分页/速率限制、交易认证、钱包/Relayer 状态、tick-size 限制和余额不足。遇到错误时，识别服务面、捕获原始响应并按上面的清单操作。Polymarket 的公共 API 与 WebSocket 端点是主要诊断面；从这些面入手。

常见问题

为什么在对 Gamma 分页 markets 时会收到 HTTP 422？

Gamma 使用键集分页。API 会用 HTTP 422 拒绝 offset。请使用上一调用返回的 after_cursor 和 limit 参数。

Polymarket geoblock 403 是什么意思，如何修复？

403 地理封锁表示你的 IP 位于 Polymarket 限制下单的司法辖区内。确认你的 IP 位置并遵循 Polymarket 的官方资格指引。不要使用 VPN 绕过封锁；如你认为这是错误，请联系支持。

我的市价单被部分成交或取消——发生了什么？

CLOB helper 默认下 FAK（Fill-And-Kill）订单。如果流动性没有完全匹配订单或滑点保护触发，剩余部分会被取消。检查订单响应以确定已成交数量，并谨慎重试。

为什么我的订单因价格增量被拒绝？

Polymarket 会强制执行 tick size（通常为 $0.01，在极端接近 0 或 1 时收紧到 $0.001）。如果你的价格或数量使用了更小的增量，订单将被拒绝或被四舍五入。订阅 Market WebSocket 的 tick_size_change 以保持最新。

我需要 API key 才能读取订单簿或 Market WebSocket 吗？

不需要。CLOB 的读取（订单簿、midpoint、价格历史）和 Market WebSocket 是公开的。CLOB 的交易端点需要 API key 和 HMAC；Gamma 与 Data 的 REST API 为公开读取。