Polymarket error codes and fixes

Ang gabay na ito ay nagpapaliwanag ng mga pinaka-karaniwang Polymarket error codes na makikita mo sa UI at mga API, bakit sila nangyayari, at konkreto at praktikal na mga hakbang para malutas ang mga ito. Kung nagde-debug ka ng integration, order flow, o koneksyon ng wallet, tutulungan ka ng gabay na ito na mabilis na ma-triage ang problema.

Key takeaways

• Nahahati ang mga Polymarket error sa ilang kategorya: geoblocking (403), API validation (422), rate limits, CLOB/trading auth, wallet o pUSD funding, at mga isyu sa CTF/CTF-operation.
• Para sa Gamma listing calls, gumamit ng cursor-based pagination (after_cursor) — tinatanggihan ang offset na may HTTP 422.
• Nangangailangan ang CLOB ng API keys + HMAC para sa trading; ang public reads ay hindi nangangailangan ng auth.
• Maraming UI "order rejected" kaso ang sanhi ng wallet deployment, kakulangan ng pUSD, approvals, pagbabago sa tick-size, o FAK partial fills — i-check ang Relayer flow at ang CLOB order response.

Bakit mahalaga ang mga error (maikli)

Ang mga error sa prediction-market flow ay maaaring mag-block ng mga order, magdulot ng partial fills, o magpatigil ng reconciliation. Gumagamit ang Polymarket ng maraming surface (Gamma, Data, CLOB, at isang Market WebSocket). Kapag alam mo kung aling surface ang nagbigay ng error, lumiliit ang saklaw ng posibleng solusyon.

H2: Common API and WebSocket error patterns

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

• Symptom: HTTP 422 kapag nag-paginate ng markets gamit ang offset.
  • Bakit: Keyset-paginated ang Gamma. Tinatanggihan ang offset.
  • Fix: Gumamit ng after_cursor gamit ang next_cursor na ibinalik ng nakaraang call. Halimbawa:

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

• Symptom: 429-like behaviour (throttling) o hindi inaasahang 5xx kapag may load.
  • Bakit: Nagpapatupad ang Gamma ng endpoint-specific rate limits (halimbawa, may limit ang /markets).
  • Fix: Sundin ang dokumentadong limits, mag-back off gamit ang exponential retry, at i-consolidate ang requests (taasan ang limit hanggang 1000 kung makatuwiran).

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

• Karaniwang reads para sa positions, trades, at open interest ay public; kung nakikita mo ang auth failures, i-verify ang eksaktong base URL at headers.

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

• Symptom: Tinanggihan ang order placement na may authentication error kapag tumatama sa trading endpoints.
  • Bakit: Nangangailangan ang trading endpoints ng API key at HMAC signature. Public ang reads (order book, midpoint, prices history).
  • Fix: Gumawa at pirmahan ang mga request ayon sa CLOB spec; subukan muna ang reads bago gumawa ng writes.

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

• Symptom: Isara ang koneksyon o walang real-time events.
  • Bakit: Inaasahan ng socket ang periodic PINGs bawat 10 s; maaari ding i-drop ng server ang idle connections. Maaari ka ring mag-subscribe ng hanggang 500 instruments lang bawat koneksyon.
  • Fix: Magpadala ng PINGs ayon sa kinakailangan at hatiin ang subscriptions sa maraming koneksyon kapag lumampas ka sa 500 instruments.

H2: Geoblock and HTTP 403 (Polymarket geoblock 403)

• Symptom: HTTP 403 kapag sinubukan mag-place ng orders o mag-access ng trading routes; nagbabalik ang UI ng geoblock message.
  • Bakit: Binablock ng Polymarket ang order placement mula sa ilang hurisdiksiyon base sa IP. Ang ilang rehiyon ay fully blocked; may ilan naman na close-only.
  • Fix: Kumpirmahin ang lokasyon ng iyong IP. Kung nasa blocked jurisdiction ka, sundin ang opisyal na guidance ng Polymarket tungkol sa eligibility. Huwag subukan i-bypass gamit ang VPN — lumalabag iyon sa Terms of Service. Kung naniniwala kang mali ang block, kontakin ang Polymarket support sa opisyal na site at magbigay ng connection diagnostics at patunay ng IP.

H2: Common "order rejected" reasons and fixes

1. Wallet not yet deployed or proxy missing

• Symptom: Nabibigo ang order sa Relayer flow na may deployment o proxy error.
• Bakit: Sinusuportahan ng Polymarket ang dalawang wallet type; ang non-Safe users ay nakakakuha ng proxy na nade-deploy sa unang transaksyon.
• Fix: Hayaan makumpleto ng Relayer ang wallet deployment flow. I-retry ang order pagkatapos makumpleto ang transaksyon.

2. Insufficient pUSD or tokens

• Symptom: Tinanggihan ang order dahil sa insufficient balance.
• Bakit: Nangangailangan ang trades ng pUSD.
• Fix: Pondohan ang account mo ng pUSD (tingnan ang guidance ng Polymarket). Kumpirmahin ang token contract at balance sa iyong wallet.

3. ERC-20 approvals and Relayer flow

• Symptom: Na-stall ang order attempt habang naghihintay ng approval.
• Bakit: Kayang hawakan ng Relayer ang approvals nang gaslessly, pero dapat makumpleto ang wallet flow.
• Fix: Kumpirmahin na natapos ang Relayer request at tingnan ang wallet UI para sa anumang pending confirmations.

4. Tick-size and minimum increment failures

• Symptom: Tinanggihan ang order o na-round nang hindi inaasahan; hindi tinatanggap ang maliliit na price differences.
• Bakit: Nagpapatupad ang Polymarket ng tick size (karaniwang $0.01, nagiging $0.001 kapag malapit sa extremes).
• Fix: I-round ang price at size ayon sa aktibong tick. Mag-subscribe sa tick_size_change sa Market WebSocket para madetekta ang mga pagbabago.

5. FAK / market order partial fills and slippage

• Symptom: Bumabalik ang market orders na may partial fills o tila kinansela.
• Bakit: Ginagamit ng CLOB helper ang FAK (Fill-And-Kill). Kung hindi completely matched ang order sa loob ng slippage protection, kino-cancel ang natira.
• Fix: I-inspect ang createMarketOrder response para sa filled quantity at i-handle ang partial fills programmatically.

6. Fee or category-related rejections

• Symptom: Nabibigo ang order na may fee-related error.
• Bakit: Nag-iiba ang taker fees ayon sa category (0%–1.8% kasalukuyang); maaaring mag-apply din ang builders ng karagdagang basis points.
• Fix: Kumpirmahin ang market category at ang iyong attribution headers kung gumagamit ng Builder. Tiyaking kasama sa iyong cost calculations ang taker fees.

H2: CTF operations and settlement errors

• Symptom: Nabibigo o nagbabalik ng error ang split/merge/redeem.
• Bakit: Ang CTF ay ang ERC-1155 outcome token framework; maaaring mabigo ang operations kung wala kang pUSD, tokens, o kung disputed ang oracle resolution.
• Fix: I-verify ang mga balances at na natapos na ang UMA resolution. Kung naka-pause ang settlement dahil sa UMA disputes, maghintay hanggang finalise ng UMA.

H2: Troubleshooting checklist (quick runbook)

• Kumpirmahin kung aling surface ang nag-ulat ng error (Gamma, Data, CLOB, o WebSocket).
• I-reproduce ang minimal failing request (GET order book o GET market) bago magsagawa ng writes.
• I-check ang wallet state: proxy deployed, pUSD balance, pending Relayer transactions.
• I-validate ang tick size at i-round nang naaayon ang inputs.
• Para sa pagination errors, lumipat sa after_cursor (Gamma).
• Sundin ang rate limits at mag-back off sa 429/5xx.

Paano ito nakakaapekto sa iyong trading o integration

Ang mga error na nagba-block ng orders ay magpapataas ng latency at makakasama sa execution quality. Gumawa ng defensive client logic: i-detect ang partial fills, ipakita ang malinaw na error messages sa mga user, at i-persist ang sapat na state para sa ligtas na retries. Para sa builders na nagro-route ng orders sa pamamagitan ng CLOB, tiyaking tama ang iyong attribution headers at API key/HMAC para maiwasan ang hindi inaasahang rejects.

Closing

Karaniwan ay tumuturo ang Polymarket error codes sa iilang pangunahing dahilan: geoblocking, pagination/rate limits, auth para sa trading, wallet/Relayer state, tick-size constraints, at insufficient balances. Kapag nakita mo ang error, tukuyin ang surface, i-capture ang raw response, at sundin ang checklist sa itaas. Ang public APIs at WebSocket endpoints ng Polymarket ang pangunahing diagnostic surfaces; doon magsimula.

Frequently asked questions

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

Gumagamit ang Gamma ng keyset pagination. Tinatanggihan ng API ang offset na may HTTP 422. Gamitin ang after_cursor value na ibinalik ng nakaraang call at ang limit parameter.

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

Ang 403 geoblock ay nagpapahiwatig na ang iyong IP ay nasa hurisdiksiyon na nililimitahan ng Polymarket para sa order placement. Kumpirmahin ang lokasyon ng iyong IP at sundin ang opisyal na eligibility guidance ng Polymarket. Huwag gumamit ng VPN para i-bypass ang block; kontakin ang support kung sa tingin mo ay mali ang block.

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

Ang CLOB helper ay naglalagay ng FAK (Fill-And-Kill) orders bilang default. Kung hindi sapat ang liquidity o na-trigger ang slippage protection, kino-cancel ang natitirang bahagi. I-inspect ang order response para malaman ang filled quantity at mag-retry nang konserbatibo.

Why are my orders rejected for price increments?

Nagpapatupad ang Polymarket ng tick size (karaniwan $0.01, nagiging $0.001 kapag malapit sa extremes). Kung mas maliit ang increment ng price o quantity na ginamit mo, tatanggihan o i-round ang order. Mag-subscribe sa tick_size_change sa Market WebSocket para manatiling up-to-date.

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

Hindi. Ang CLOB reads (order book, midpoint, price history) at ang Market WebSocket ay public. Nangangailangan ng API key at HMAC ang trading endpoints sa CLOB; ang Gamma at Data REST APIs ay public reads.