Polymarket error codes and fixes

このガイドでは、UI や API で遭遇することが多い Polymarket のエラーコードが何を意味するか、そして開発者やアクティブユーザー向けの実用的な対処法を説明します。統合、注文フロー、ウォレット接続のデバッグを行う際に、問題を迅速に特定するのに役立ちます。

主なポイント

• Polymarket のエラーは大きく分けていくつかのカテゴリに分類されます：ジオブロッキング（403）、API バリデーション（422）、レート制限、CLOB/取引の認証、ウォレットや pUSD の資金不足、CTF 操作の問題。
• Gamma の一覧取得では、カーソルベースのページネーション（after_cursor）を使ってください — offset は HTTP 422 で拒否されます。
• CLOB は取引に API キーと HMAC を必要とします。読み取りは認証不要です。
• 多くの UI の「order rejected」は、ウォレットのデプロイ、pUSD 不足、承認、ティックサイズの変更、あるいは FAK の部分約定が原因です — Relayer フローと CLOB の注文レスポンスを確認してください。

エラーが重要な理由（簡潔）

予測市場のフローでのエラーは、注文のブロック、部分約定、または照合の停止を引き起こす可能性があります。Polymarket は複数のサーフェス（Gamma、Data、CLOB、および Market WebSocket）を使用しています。どのサーフェスがエラーを返したかを知ることは、修正箇所を絞るのに有用です。

H2: 一般的な API と WebSocket のエラーパターン

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

• 症状: offset を使ってマーケットをページングすると HTTP 422 が返る。
  • 理由: Gamma はキーセットページネーションを採用しており、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 キーと HMAC 署名を要求します。読み取り（注文板、ミッドポイント、価格履歴）は公開です。
  • 修正: CLOB 仕様に従ってリクエストを生成し署名してください。書き込みを試す前に読み取りをテストしてください。

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

• 症状: 接続が切れる、またはリアルタイムイベントが来ない。
  • 理由: ソケットは 10 s ごとの PING を期待します。アイドル状態の接続はサーバーに切られることがあります。また、1 接続あたり最大 500 インストゥルメントにしかサブスクライブできません。
  • 修正: 必要な PING を送信し、500 を超える場合はサブスクリプションを接続間で分割してください。

H2: ジオブロックと HTTP 403（Polymarket geoblock 403）

• 症状: 注文を出そうとしたり取引ルートにアクセスしようとすると HTTP 403 が返り、UI にジオブロックメッセージが表示される。
  • 理由: Polymarket は特定の管轄区域からの IP に対して注文の配置をブロックします。一部の地域は完全にブロックされ、いくつかはクローズのみ許可されています。
  • 修正: IP の位置を確認してください。ブロックされた地域にいる場合は、Polymarket の公式の適格性ガイダンスに従ってください。VPN を使った回避は利用規約違反です。ブロックが誤りだと思う場合は、公式サイトから Polymarket サポートに接続診断と IP 証拠を添えて連絡してください。

H2: 一般的な「order rejected」の理由と修正

1. ウォレットがまだデプロイされていない、またはプロキシが不足している

• 症状: Relayer フロー中にデプロイまたはプロキシのエラーで注文が失敗する。
• 理由: Polymarket は 2 種類のウォレットをサポートします。Safe を使っていないユーザーには初回トランザクション時にプロキシがデプロイされます。
• 修正: Relayer のウォレットデプロイフローが完了するのを待ってください。トランザクション完了後に注文を再試行してください。

2. pUSD やトークンの不足

• 症状: 残高不足で注文が拒否される。
• 理由: 取引には pUSD が必要です。
• 修正: アカウントに pUSD を入金してください（Polymarket のガイダンス参照）。ウォレット内のトークンコントラクトと残高を確認してください。

3. ERC-20 承認と Relayer フロー

• 症状: 承認を待っている間に注文が停滞する。
• 理由: Relayer は承認をガスレスで処理できますが、ウォレットフローが完了する必要があります。
• 修正: Relayer リクエストが完了したか確認し、ウォレット UI に保留中の確認がないかチェックしてください。

4. ティックサイズと最小刻みエラー

• 症状: 注文が拒否される、または予期せず丸められる。小さな価格差が受け入れられない。
• 理由: Polymarket はティックサイズを強制します（通常 $0.01、価格が極端な場合は $0.001 にタイト化）。
• 修正: アクティブなティックに価格とサイズを丸めてください。Market WebSocket の tick_size_change を購読して変更を検出します。

5. FAK / マーケット注文の部分約定とスリッページ

• 症状: マーケット注文が部分約定で返る、またはキャンセルされたように見える。
• 理由: CLOB のヘルパーは FAK (Fill-And-Kill) を使用します。スリッページ保護や流動性不足で未約定分はキャンセルされます。
• 修正: createMarketOrder のレスポンスで約定量を確認し、プログラム的に部分約定を処理してください。

6. 手数料やカテゴリ関連の拒否

• 症状: 手数料に関連するエラーで注文が失敗する。
• 理由: テイカーフィーはカテゴリごとに変動します（現在 0%〜1.8%）。Builder が追加のベーシスポイントを適用する場合もあります。
• 修正: マーケットのカテゴリと、Builder を使う場合は帰属ヘッダーを確認してください。コスト計算にテイカーフィーを含めていることを確認してください。

H2: CTF 操作と決済エラー

• 症状: split/merge/redeem が失敗するかエラーを返す。
• 理由: CTF は ERC-1155 のアウトカムトークンフレームワークです。pUSD やトークンが不足している場合、あるいはオラクルの決議が異議申し立て中だと操作が失敗することがあります。
• 修正: 残高を確認し、UMA の決議が完了していることを確認してください。UMA の異議申し立てで決済が保留されている場合は、UMA の確定を待ってください。

H2: トラブルシューティングチェックリスト（クイックランブック）

• どのサーフェスがエラーを報告したかを確認する（Gamma、Data、CLOB、または WebSocket）。
• 書き込みを試す前に、失敗する最小のリクエスト（GET order book や GET market）を再現する。
• ウォレット状態を確認する：プロキシがデプロイ済みか、pUSD の残高、保留中の Relayer トランザクション。
• ティックサイズを検証し、入力をそれに合わせて丸める。
• ページネーションエラーがある場合は after_cursor に切り替える（Gamma）。
• レート制限を尊重し、429/5xx の際はバックオフする。

取引や統合に与える影響

注文をブロックするエラーはレイテンシを増やし、実行品質を損ないます。防御的なクライアントロジックを構築してください：部分約定を検出し、ユーザーに明確なエラーメッセージを表示し、安全にリトライするための十分な状態を永続化してください。CLOB を通して注文をルーティングする Builder は、帰属ヘッダーと API キー/HMAC が正しいことを確認して、予期せぬ拒否を避けてください。

締め

Polymarket のエラーコードは通常、少数の根本原因を示します：ジオブロッキング、ページネーション/レート制限、取引の認証、ウォレット/Relayer 状態、ティックサイズの制約、残高不足。エラーを見たらサーフェスを特定し、生のレスポンスをキャプチャし、上記のチェックリストに従ってください。Polymarket の公開 API と WebSocket エンドポイントは主な診断サーフェスです。まずそこから始めてください。

Frequently asked questions

Why do I get HTTP 422 from Gamma when paginating markets?

Gamma はキーセットページネーションを使用します。API は offset を HTTP 422 で拒否します。前回の呼び出しで返された after_cursor を使用し、limit パラメータと組み合わせてください。

What does Polymarket geoblock 403 mean and how do I fix it?

403 のジオブロックは、あなたの IP が Polymarket が注文配置を制限する管轄区域にあることを示します。IP の位置を確認し、Polymarket の公式の適格性ガイダンスに従ってください。ブロックを回避するために VPN を使用しないでください。誤りだと思う場合はサポートに連絡してください。

My market order was partially filled or cancelled — what happened?

CLOB のヘルパーはデフォルトで FAK (Fill-And-Kill) 注文を配置します。流動性が注文を完全にマッチしなかったか、スリッページ保護が発動した場合、未約定分はキャンセルされます。注文レスポンスを確認して約定量を把握し、慎重に再試行してください。

Why are my orders rejected for price increments?

Polymarket はティックサイズを強制します（通常 $0.01、極端な価格帯では $0.001 にタイト化）。価格や数量が小さい刻みを使っている場合、注文は拒否されるか丸められます。Market WebSocket の tick_size_change を購読して最新状態を維持してください。

Do I need API keys to read order books or the Market WebSocket?

いいえ。CLOB の読み取り（注文板、ミッドポイント、価格履歴）と Market WebSocket は公開です。CLOB の取引エンドポイントは API キーと HMAC が必要です。Gamma と Data の REST API は公開読み取りです。