Kode kesalahan Polymarket dan perbaikannya

Panduan ini menjelaskan kode kesalahan Polymarket yang paling umum yang akan Anda lihat di UI dan API, mengapa mereka terjadi, dan langkah konkret untuk memperbaikinya. Jika Anda sedang men-debug integrasi, alur order, atau koneksi wallet, panduan ini membantu Anda mendiagnosa masalah dengan cepat.

Poin kunci

• Kesalahan Polymarket termasuk beberapa kategori: geoblocking (403), validasi API (422), batas laju, otentikasi CLOB/trading, wallet atau pendanaan pUSD, dan masalah operasi CTF.
• Untuk panggilan listing Gamma, gunakan paginasi berbasis cursor (after_cursor) — offset ditolak dengan HTTP 422.
• CLOB membutuhkan API key + HMAC untuk trading; baca publik tidak memerlukan otentikasi.
• Banyak kasus UI "order rejected" disebabkan oleh deployment wallet, pUSD tidak cukup, approval yang belum selesai, perubahan tick-size, atau FAK partial fill — periksa alur Relayer dan response order CLOB.

Mengapa kesalahan penting (singkat)

Kesalahan dalam alur pasar prediksi dapat memblokir order, menyebabkan partial fill, atau menghambat rekonsiliasi. Polymarket menggunakan banyak permukaan (Gamma, Data, CLOB, dan Market WebSocket). Mengetahui permukaan mana yang menghasilkan kesalahan mempersempit langkah perbaikan.

H2: Pola kesalahan umum pada API dan WebSocket

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

• Gejala: HTTP 422 saat melakukan paginasi markets menggunakan offset.
  • Mengapa: Gamma menggunakan paginasi keyset. offset ditolak.
  • Perbaikan: Gunakan after_cursor dengan next_cursor yang dikembalikan oleh panggilan sebelumnya. Contoh:

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

• Gejala: Perilaku mirip 429 (throttling) atau 5xx yang tidak terduga saat beban tinggi.
  • Mengapa: Gamma menerapkan batas laju spesifik-endpoint (misalnya /markets memiliki batas).
  • Perbaikan: Hormati batas yang didokumentasikan, lakukan back off dengan retry eksponensial, dan konsolidasikan permintaan (tingkatkan limit sampai 1000 jika masuk akal).

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

• Baca umum untuk posisi, trades, dan open interest bersifat publik; jika Anda melihat kegagalan otentikasi, verifikasi URL dasar dan header dengan tepat.

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

• Gejala: Penempatan order ditolak dengan kesalahan otentikasi saat memanggil endpoint trading.
  • Mengapa: Endpoint trading membutuhkan API key dan signature HMAC. Baca (order book, midpoint, prices history) bersifat publik.
  • Perbaikan: Buat dan tanda tangani permintaan sesuai spesifikasi CLOB; uji baca terlebih dahulu sebelum menulis.

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

• Gejala: Koneksi terputus atau tidak ada event real-time.
  • Mengapa: Socket mengharapkan PING periodik setiap 10 s; server dapat memutus koneksi yang menganggur. Juga, Anda bisa berlangganan maksimal 500 instrument per koneksi.
  • Perbaikan: Kirim PING sesuai yang diperlukan dan pecah langganan ke beberapa koneksi saat melebihi 500 instrument.

H2: Geoblock dan HTTP 403 (Polymarket geoblock 403)

• Gejala: HTTP 403 saat mencoba menempatkan order atau mengakses rute trading; UI menampilkan pesan geoblock.
  • Mengapa: Polymarket memblokir penempatan order dari yurisdiksi tertentu berdasarkan IP. Beberapa wilayah sepenuhnya diblokir; beberapa hanya bisa menutup posisi (close-only).
  • Perbaikan: Konfirmasi lokasi IP Anda. Jika Anda berada di yurisdiksi yang diblokir, ikuti panduan resmi Polymarket tentang kelayakan. Jangan mencoba mem-bypass dengan VPN — itu melanggar Terms of Service. Jika Anda percaya blok ini adalah kesalahan, hubungi dukungan Polymarket melalui situs resmi dan sertakan diagnostik koneksi serta bukti IP.

H2: Alasan "order rejected" yang umum dan perbaikannya

1. Wallet belum dideploy atau proxy hilang

• Gejala: Order gagal selama alur Relayer dengan error deployment atau proxy.
• Mengapa: Polymarket mendukung dua tipe wallet; pengguna non-Safe mendapatkan proxy yang dideploy pada transaksi pertama.
• Perbaikan: Biarkan Relayer menyelesaikan alur deployment wallet. Coba ulang order setelah transaksi selesai.

2. pUSD atau token tidak cukup

• Gejala: Order ditolak karena saldo tidak mencukupi.
• Mengapa: Trading membutuhkan pUSD.
• Perbaikan: Danai akun Anda dengan pUSD (lihat panduan Polymarket). Konfirmasi kontrak token dan saldo di wallet Anda.

3. ERC-20 approvals dan alur Relayer

• Gejala: Percobaan order terhenti menunggu approval.
• Mengapa: Relayer dapat menangani approval secara gasless, tetapi alur wallet harus selesai.
• Perbaikan: Konfirmasi permintaan Relayer telah selesai dan periksa UI wallet Anda untuk konfirmasi yang tertunda.

4. Tick-size dan kegagalan kenaikan minimum

• Gejala: Order ditolak atau dibulatkan secara tak terduga; selisih harga kecil tidak diterima.
• Mengapa: Polymarket menerapkan tick size (biasanya $0.01, mengerucut ke $0.001 saat harga mendekati ekstrem).
• Perbaikan: Bulatkan harga dan ukuran ke tick aktif. Berlangganan tick_size_change lewat Market WebSocket untuk mendeteksi perubahan.

5. FAK / market order partial fills dan slippage

• Gejala: Market order mengembalikan partial fill atau terlihat dibatalkan.
• Mengapa: Helper CLOB menggunakan FAK (Fill-And-Kill). Jika tidak terisi penuh dalam proteksi slippage, sisa order dibatalkan.
• Perbaikan: Periksa response createMarketOrder untuk kuantitas yang terisi dan tangani partial fill secara programatik.

6. Penolakan terkait fee atau kategori

• Gejala: Order gagal dengan error terkait fee.
• Mengapa: Taker fee bervariasi menurut kategori (0%–1.8% saat ini); builder dapat menambahkan basis poin tambahan.
• Perbaikan: Konfirmasi kategori pasar dan header atribusi Anda jika menggunakan Builder. Pastikan perhitungan biaya Anda memasukkan taker fee.

H2: Operasi CTF dan kesalahan settlement

• Gejala: split/merge/redeem gagal atau mengembalikan error.
• Mengapa: CTF adalah framework token outcome ERC-1155; operasi bisa gagal jika Anda kekurangan pUSD, token, atau jika resolusi oracle sedang diperdebatkan.
• Perbaikan: Verifikasi saldo dan bahwa resolusi UMA telah selesai. Jika UMA menunda settlement karena dispute, tunggu sampai UMA memutuskan secara final.

H2: Checklist troubleshooting (runbook singkat)

• Konfirmasi permukaan mana yang melaporkan error (Gamma, Data, CLOB, atau WebSocket).
• Reproduksi request minimal yang gagal (GET order book atau GET market) sebelum mencoba menulis.
• Periksa status wallet: proxy ter-deploy, saldo pUSD, transaksi Relayer yang tertunda.
• Validasi tick size dan bulatkan input sesuai.
• Untuk kesalahan paginasi, beralih ke after_cursor (Gamma).
• Hormati batas laju dan lakukan back off pada 429/5xx.

Bagaimana ini memengaruhi trading atau integrasi Anda

Kesalahan yang memblokir order akan menambah latensi dan merusak kualitas eksekusi. Bangun logika klien defensif: deteksi partial fill, tampilkan pesan error yang jelas ke pengguna, dan simpan cukup state untuk percobaan ulang yang aman. Untuk builder yang merutekan order melalui CLOB, pastikan header atribusi dan API key/HMAC Anda benar untuk menghindari penolakan tak terduga.

Penutup

Kode kesalahan Polymarket biasanya menunjuk ke sejumlah kecil penyebab akar: geoblocking, paginasi/batas laju, otentikasi untuk trading, status wallet/Relayer, batasan tick-size, dan saldo tidak cukup. Ketika Anda melihat error, identifikasi permukaan, tangkap response mentah, dan ikuti checklist di atas. API publik dan endpoint WebSocket Polymarket adalah permukaan diagnostik utama; mulailah dari sana.

Pertanyaan yang sering diajukan

Mengapa saya mendapat HTTP 422 dari Gamma saat melakukan paginasi markets?

Gamma menggunakan paginasi keyset. API menolak offset dengan HTTP 422. Gunakan nilai after_cursor yang dikembalikan oleh panggilan sebelumnya dan parameter limit sebagai gantinya.

Apa arti Polymarket geoblock 403 dan bagaimana cara memperbaikinya?

403 geoblock menandakan IP Anda berada di yurisdiksi yang dibatasi Polymarket untuk penempatan order. Konfirmasi lokasi IP Anda dan ikuti panduan kelayakan resmi Polymarket. Jangan gunakan VPN untuk melewati blok; hubungi dukungan jika Anda yakin ini adalah kesalahan.

Order market saya terisi sebagian atau dibatalkan — apa yang terjadi?

Helper CLOB menempatkan order FAK (Fill-And-Kill) secara default. Jika likuiditas tidak mencukupi atau proteksi slippage terpicu, sisa order dibatalkan. Periksa response order untuk menentukan kuantitas yang terisi dan coba ulang secara konservatif.

Mengapa order saya ditolak karena kenaikan harga?

Polymarket menerapkan tick size (biasanya $0.01, mengerucut ke $0.001 saat harga mendekati ekstrem). Jika harga atau kuantitas Anda menggunakan kenaikan lebih kecil, order akan ditolak atau dibulatkan. Berlangganan tick_size_change pada Market WebSocket untuk tetap up-to-date.

Apakah saya perlu API key untuk membaca order book atau Market WebSocket?

Tidak. Baca CLOB (order book, midpoint, price history) dan Market WebSocket bersifat publik. Endpoint trading pada CLOB membutuhkan API key dan HMAC; Gamma dan Data REST API adalah baca publik.