Polymarket 錯誤代碼與修復

本指南說明你在 UI 與 API 中最常遇到的 Polymarket 錯誤代碼、錯誤原因，以及具體的檢查與修復步驟。若你在除錯整合、訂單流程或錢包連線時卡住，這份指南能協助你快速判定問題。

重點摘要

• Polymarket 的錯誤大致可分類為：地區封鎖（403）、API 驗證（422）、速率限制、CLOB/交易授權、錢包或 pUSD 餘額，以及 CTF/CTF 操作問題。
• 對於 Gamma 的 listings 呼叫，請使用基於游標的分頁（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 分頁市場時收到 HTTP 422。
  • 原因：Gamma 採用 keyset 分頁。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)

• 讀取 positions、trades 與 open interest 等常見資料是公開的；若看到授權失敗，請確認你使用的 base URL 與標頭是否正確。

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

• 症狀：在呼叫交易端點時收到授權錯誤導致訂單被拒絕。
  • 原因：交易端點需要 API key 與 HMAC 簽名。讀取（order book、midpoint、prices history）為公開。
  • 修復：依 CLOB 規格產生與簽署請求；先測試讀取端點再進行寫入。

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

• 症狀：連線被關閉或沒有即時事件。
  • 原因：Socket 需要每 10 秒送出 PING；伺服器可能會斷開閒置連線。另外，每個連線最多可訂閱 500 個標的。
  • 修復：依需求傳送 PING，當訂閱超過 500 個標的時拆分成多個連線。

H2: 地區封鎖與 HTTP 403（Polymarket geoblock 403）

• 症狀：嘗試下單或進入交易路徑時收到 HTTP 403；UI 顯示地區封鎖訊息。
  • 原因：Polymarket 依 IP 阻擋某些司法轄區的下單行為。部分地區為完全封鎖；少數地區為僅可平倉（close-only）。
  • 修復：確認你的 IP 所在位置。若你身處被封鎖的司法轄區，請遵循 Polymarket 官方關於資格的說明。切勿嘗試使用 VPN 覆蓋封鎖——那違反服務條款。如果你認為封鎖為錯誤，請透過官方網站聯絡 Polymarket 支援，並提供連線診斷與 IP 證據。

H2: 常見的「訂單被拒絕」原因與修復

1. 錢包尚未部署或 proxy 遺失

• 症狀：訂單在 Relayer 流程中於部署或 proxy 階段失敗。
• 原因：Polymarket 支援兩種錢包型態；非 Safe 使用者的 proxy 會在第一次交易時自動部署。
• 修復：讓 Relayer 完成錢包部署流程。交易完成後重試訂單。

2. pUSD 或代幣不足

• 症狀：因餘額不足導致訂單被拒絕。
• 原因：交易需要用到 pUSD。
• 修復：為帳戶補足 pUSD（參考 Polymarket 指引）。確認錢包中代幣合約與餘額。

3. ERC-20 核准（approval）與 Relayer 流程

• 症狀：訂單嘗試停在等待核准的狀態。
• 原因：Relayer 可以無 gas 處理核准，但錢包端的流程仍需完成。
• 修復：確認 Relayer 請求已完成，並檢查錢包介面是否有待處理的確認項目。

4. Tick-size 與最小增量失敗

• 症狀：訂單被拒絕或被意外四捨五入；小幅價格差異不被接受。
• 原因：Polymarket 強制 tick size（通常為 $0.01，接近極端價格時收緊為 $0.001）。
• 修復：將價格與數量依當前 tick 四捨五入。訂閱 Market WebSocket 的 tick_size_change 事件以偵測變動。

5. FAK / 市價單的部分成交與滑價

• 症狀：市價單回傳部分成交或看似被取消。
• 原因：CLOB 的 helper 會使用 FAK（Fill-And-Kill）。若未在滑價保護內完全撮合，未成交的部分會被取消。
• 修復：檢查 createMarketOrder 的回應以得知已成交數量，並在程式邏輯中處理部分成交。

6. 費用或分類相關的拒絕

• 症狀：訂單因費用相關錯誤而失敗。
• 原因：Taker 費用依市場分類有所不同（目前範圍 0%–1.8%）；Builder 可能會額外加 basis points。
• 修復：確認市場分類以及在使用 Builder 時的 attribution headers。確保你的成本計算包含 taker fee。

H2: CTF 操作與結算錯誤

• 症狀：split/merge/redeem 失敗或回傳錯誤。
• 原因：CTF 為 ERC-1155 的結果代幣框架；若你缺乏 pUSD、代幣，或 Oracle 結果遭到爭議，操作會失敗。
• 修復：驗證餘額並確認 UMA 已完成解析。若 UMA 的爭議使結算暫停，需等待 UMA 定案。

H2: 疑難排解檢查清單（快速執行手冊）

• 確認是哪一個介面回報錯誤（Gamma、Data、CLOB 或 WebSocket）。
• 在嘗試寫入前，重現最小失敗請求（GET order book 或 GET market）。
• 檢查錢包狀態：proxy 是否已部署、pUSD 餘額、Relayer 是否有待處理的交易。
• 驗證 tick size 並依此四捨五入輸入值。
• 對於分頁錯誤，改用 after_cursor（Gamma）。
• 遵守速率限制，對 429/5xx 做退避處理。

此對你的交易或整合有何影響

會阻礙下單的錯誤會增加延遲並降低執行品質。請在客戶端實作防禦性邏輯：偵測部分成交、向使用者呈現清楚的錯誤訊息，並持久化足夠的狀態以安全重試。對於透過 CLOB 路由訂單的 Builders，請確認你的 attribution headers 與 API key/HMAC 正確，避免意外的拒絕。

結語

Polymarket 的錯誤代碼通常指向少數根本原因：地區封鎖、分頁/速率限制、交易授權、錢包/Relayer 狀態、tick-size 限制與餘額不足。遇到錯誤時，先判別介面、擷取原始回應，並依上方檢查清單處理。Polymarket 的公開 API 與 WebSocket 端點是主要的診斷面向，建議從這些介面開始檢查。

常見問答

為何在對 Gamma 做市場分頁時會收到 HTTP 422？

Gamma 採用 keyset 分頁。API 會以 HTTP 422 拒絕 offset。請使用前一次回傳的 after_cursor 與 limit 參數。

Polymarket geoblock 403 是什麼意思，我要如何修復？

403 geoblock 表示你的 IP 位於 Polymarket 限制下單的司法轄區。請確認你的 IP 所在位置並遵循 Polymarket 的官方資格說明。切勿使用 VPN 覆蓋封鎖；若你認為封鎖為錯誤，請聯絡支援。

我的市場訂單被部分成交或取消——發生了什麼事？

CLOB 的 helper 預設放置 FAK（Fill-And-Kill）訂單。若流動性未能完全撮合或滑價保護觸發，剩餘部分會被取消。檢查訂單回應以確定已成交量，並保守地重試。

為何我的訂單因價格增量而被拒絕？

Polymarket 強制 tick size（通常為 $0.01，接近極端價格時收緊為 $0.001）。若你的價格或數量使用更小的增量，訂單會被拒絕或被四捨五入。訂閱 Market WebSocket 的 tick_size_change 以保持同步。

讀取 order book 或 Market WebSocket 需要 API key 嗎？

不需要。CLOB 的讀取（order book、midpoint、price history）以及 Market WebSocket 是公開的。CLOB 的交易端點需要 API key 與 HMAC；Gamma 與 Data REST API 則為公開讀取。