Polymarket error codes and fixes

This guide explains the most common Polymarket error codes you’ll see in the UI and APIs, why they happen, and concrete steps to resolve them. If you’re debugging an integration, order flow, or a wallet connection, this guide helps you triage the problem quickly.

Key takeaways

• Polymarket errors fall into a few buckets: geoblocking (403), API validation (422), rate limits, CLOB/trading auth, wallet or pUSD funding, and CTF/CTF-operation issues.
• For Gamma listing calls, use cursor-based pagination (after_cursor) — offset is rejected with HTTP 422.
• The CLOB requires API keys + HMAC for trading; public reads don’t need auth.
• Many UI "order rejected" cases are caused by wallet deployment, insufficient pUSD, approvals, tick-size changes, or FAK partial fills — check the Relayer flow and CLOB order response.

Why errors matter (short)

Errors in a prediction-market flow can block orders, cause partial fills, or stall reconciliation. Polymarket uses multiple surfaces (Gamma, Data, CLOB, and a Market WebSocket). Knowing which surface threw the error narrows the fix.

H2: Common API and WebSocket error patterns

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

• Symptom: HTTP 422 when paginating markets using offset.
  • Why: Gamma is keyset-paginated. offset is rejected.
  • Fix: Use after_cursor with the next_cursor returned by the previous call. Example:

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

• Symptom: 429-like behaviour (throttling) or unpredictable 5xx under load.
  • Why: Gamma enforces endpoint-specific rate limits (for example /markets has a limit).
  • Fix: Respect the documented limits, back off with exponential retry, and consolidate requests (increase limit up to 1000 where sensible).

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

• Common reads for positions, trades, and open interest are public; if you see auth failures, verify the exact base URL and headers.

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

• Symptom: Order placement rejected with an authentication error when hitting the trading endpoints.
  • Why: Trading endpoints require an API key and an HMAC signature. Reads (order book, midpoint, prices history) are public.
  • Fix: Generate and sign requests per the CLOB spec; test reads first before attempting writes.

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

• Symptom: Connection closed or no real-time events.
  • Why: The socket expects periodic PINGs every 10 s; servers may drop idle connections. Also, you can subscribe to a maximum of 500 instruments per connection.
  • Fix: Send PINGs as required and split subscriptions across connections when you exceed 500 instruments.

H2: Geoblock and HTTP 403 (Polymarket geoblock 403)

• Symptom: HTTP 403 when attempting to place orders or access trading routes; UI returns a geoblock message.
  • Why: Polymarket blocks order placement from certain jurisdictions by IP. Some regions are fully blocked; a few are close-only.
  • Fix: Confirm your IP location. If you’re in a blocked jurisdiction, follow Polymarket’s official guidance on eligibility. Do not attempt VPN bypass — that violates Terms of Service. If you believe the block is an error, contact Polymarket support via the official site and provide connection diagnostics and IP evidence.

H2: Common "order rejected" reasons and fixes

1. Wallet not yet deployed or proxy missing

• Symptom: Order fails during the Relayer flow with a deployment or proxy error.
• Why: Polymarket supports two wallet types; non-Safe users get a proxy deployed on first transaction.
• Fix: Let the Relayer complete the wallet deployment flow. Retry the order after the transaction completes.

2. Insufficient pUSD or tokens

• Symptom: Order rejected due to insufficient balance.
• Why: Trades require pUSD.
• Fix: Fund your account with pUSD (see Polymarket’s guidance). Confirm token contract and balance in your wallet.

3. ERC-20 approvals and Relayer flow

• Symptom: Order attempt stalls waiting for approval.
• Why: The Relayer can handle approvals gaslessly, but the wallet flow must complete.
• Fix: Confirm the Relayer request completed and check your wallet UI for any pending confirmations.

4. Tick-size and minimum increment failures

• Symptom: Order rejected or rounded unexpectedly; small price differences are not accepted.
• Why: Polymarket enforces a tick size (usually $0.01, tightening to $0.001 near extremes).
• Fix: Round price and size to the active tick. Subscribe to tick_size_change over the Market WebSocket to detect changes.

5. FAK / market order partial fills and slippage

• Symptom: Market orders return partial fills or appear cancelled.
• Why: The CLOB helper uses FAK (Fill-And-Kill). If not fully matched within slippage protection, the remainder is cancelled.
• Fix: Inspect the createMarketOrder response for filled quantity and handle partial fills programmatically.

6. Fee or category-related rejections

• Symptom: Order fails with a fee-related error.
• Why: Taker fees vary by category (0%–1.8% currently); builders can apply additional basis points.
• Fix: Confirm the market category and your attribution headers if using a Builder. Ensure your cost calculations include taker fees.

H2: CTF operations and settlement errors

• Symptom: split/merge/redeem fails or returns an error.
• Why: CTF is the ERC-1155 outcome token framework; operations can fail if you lack pUSD, tokens, or if the oracle resolution is disputed.
• Fix: Verify balances and that UMA resolution has completed. If UMA disputes pause settlement, wait until UMA finalises.

H2: Troubleshooting checklist (quick runbook)

• Confirm which surface reported the error (Gamma, Data, CLOB, or WebSocket).
• Reproduce the minimal failing request (GET order book or GET market) before attempting writes.
• Check wallet state: proxy deployed, pUSD balance, pending Relayer transactions.
• Validate tick size and round inputs accordingly.
• For pagination errors, switch to after_cursor (Gamma).
• Respect rate limits and back off on 429/5xx.

How this affects your trading or integration

Errors that block orders will increase latencies and hurt execution quality. Build defensive client logic: detect partial fills, surface clear error messages to users, and persist enough state for safe retries. For builders routing orders through the CLOB, ensure your attribution headers and API key/HMAC are correct to avoid unexpected rejects.

Closing

Polymarket error codes usually point to a small number of root causes: geoblocking, pagination/rate limits, auth for trading, wallet/Relayer state, tick-size constraints, and insufficient balances. When you see an error, identify the surface, capture the raw response, and follow the checklist above. Polymarket’s public APIs and WebSocket endpoints are the primary diagnostic surfaces; start there.

Frequently asked questions

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

Gamma uses keyset pagination. The API rejects offset with HTTP 422. Use the after_cursor value returned by the previous call and the limit parameter instead.

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

A 403 geoblock indicates your IP is in a jurisdiction Polymarket restricts for order placement. Confirm your IP location and follow Polymarket’s official eligibility guidance. Do not use VPNs to bypass the block; contact support if you believe it’s an error.

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

The CLOB helper places FAK (Fill-And-Kill) orders by default. If liquidity didn’t fully match the order or slippage protection triggered, the remainder is cancelled. Inspect the order response to determine the filled quantity and retry conservatively.

Why are my orders rejected for price increments?

Polymarket enforces a tick size (typically $0.01, tightening to $0.001 near extremes). If your price or quantity uses a smaller increment, the order will be rejected or rounded. Subscribe to tick_size_change on the Market WebSocket to stay current.

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

No. CLOB reads (order book, midpoint, price history) and the Market WebSocket are public. Trading endpoints on the CLOB require an API key and HMAC; Gamma and Data REST APIs are public reads.