Codici di errore di Polymarket e soluzioni

Questa guida spiega i codici di errore Polymarket più comuni che vedrai nell'interfaccia e nelle API, perché si verificano e passi concreti per risolverli. Se stai debugando un'integrazione, il flusso d'ordine o una connessione wallet, questa guida ti aiuta a individuare rapidamente il problema.

Punti chiave

• Gli errori Polymarket ricadono in alcuni gruppi: geoblocking (403), validazione API (422), limiti di richiesta, autenticazione CLOB/trading, wallet o finanziamento pUSD e problemi con le operazioni CTF.
• Per le chiamate di listing Gamma, usa la paginazione basata su cursore (after_cursor) — offset viene respinto con HTTP 422.
• Il CLOB richiede API key + HMAC per il trading; le letture pubbliche non necessitano autenticazione.
• Molti casi di "ordine rifiutato" nell'interfaccia sono causati da deployment wallet, pUSD insufficiente, approvazioni mancanti, cambi di tick-size o fill parziali FAK — controlla il flusso del Relayer e la risposta dell'ordine CLOB.

Perché gli errori sono importanti (breve)

Gli errori in un flusso di prediction-market possono bloccare ordini, causare fill parziali o rallentare la riconciliazione. Polymarket usa più superfici (Gamma, Data, CLOB e un Market WebSocket). Sapere quale superficie ha generato l'errore restringe le possibili soluzioni.

H2: Modelli comuni di errore in API e WebSocket

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

• Sintomo: HTTP 422 durante la paginazione dei mercati usando offset.
  • Perché: Gamma usa paginazione keyset. offset viene respinto.
  • Soluzione: Usa after_cursor con il next_cursor restituito dalla chiamata precedente. Esempio:

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

• Sintomo: comportamento simile a 429 (throttling) o 5xx imprevedibili sotto carico.
  • Perché: Gamma applica limiti di richiesta specifici per endpoint (ad es. /markets ha un limite).
  • Soluzione: Rispetta i limiti documentati, applica backoff esponenziale e consolida le richieste (aumenta limit fino a 1000 dove sensato).

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

• Le letture comuni per posizioni, trade e open interest sono pubbliche; se vedi errori di autenticazione, verifica l'URL di base esatto e le intestazioni.

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

• Sintomo: invio ordine rifiutato con errore di autenticazione quando si colpiscono gli endpoint di trading.
  • Perché: Gli endpoint di trading richiedono una API key e una firma HMAC. Le letture (order book, midpoint, prezzi storici) sono pubbliche.
  • Soluzione: Genera e firma le richieste secondo le specifiche CLOB; testa prima le letture e poi le scritture.

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

• Sintomo: connessione chiusa o assenza di eventi in tempo reale.
  • Perché: Il socket si aspetta PING periodici ogni 10 s; i server possono chiudere connessioni inattive. Inoltre puoi sottoscrivere al massimo 500 strumenti per connessione.
  • Soluzione: Invia i PING richiesti e dividi le sottoscrizioni su più connessioni quando superi i 500 strumenti.

H2: Geoblock e HTTP 403 (Polymarket geoblock 403)

• Sintomo: HTTP 403 quando tenti di piazzare ordini o accedere a rotte di trading; l'interfaccia restituisce un messaggio di geoblock.
  • Perché: Polymarket blocca l'invio di ordini da certe giurisdizioni in base all'IP. Alcune regioni sono completamente bloccate; altre sono solo close-only.
  • Soluzione: Conferma la posizione del tuo IP. Se sei in una giurisdizione bloccata, segui le indicazioni ufficiali di Polymarket sull'idoneità. Non provare a bypassare con VPN — ciò viola i Termini di Servizio. Se pensi che il blocco sia un errore, contatta il supporto Polymarket tramite il sito ufficiale e fornisci diagnostica di connessione e prove dell'IP.

H2: Motivi comuni di "ordine rifiutato" e rimedi

1. Wallet non ancora deployato o proxy mancante

• Sintomo: l'ordine fallisce durante il flusso del Relayer con un errore di deployment o proxy.
• Perché: Polymarket supporta due tipi di wallet; gli utenti non-Safe ricevono un proxy deployato alla prima transazione.
• Soluzione: Lascia che il Relayer completi il flusso di deployment del wallet. Ritenta l'ordine dopo il completamento della transazione.

2. pUSD o token insufficienti

• Sintomo: ordine rifiutato per saldo insufficiente.
• Perché: Le operazioni richiedono pUSD.
• Soluzione: Rifornisci il tuo account con pUSD (vedi le indicazioni di Polymarket). Verifica il contratto token e il saldo nel tuo wallet.

3. Approvazioni ERC-20 e flusso del Relayer

• Sintomo: tentativo d'ordine rimane in attesa per approvazione.
• Perché: Il Relayer può gestire le approvazioni senza gas, ma il flusso wallet deve comunque completarsi.
• Soluzione: Conferma che la richiesta al Relayer sia completata e controlla l'interfaccia del wallet per eventuali conferme in sospeso.

4. Fallimenti dovuti a tick-size e incrementi minimi

• Sintomo: ordine rifiutato o arrotondato inaspettatamente; piccole differenze di prezzo non sono accettate.
• Perché: Polymarket applica una tick size (di solito $0.01, che si restringe a $0.001 vicino agli estremi).
• Soluzione: Arrotonda prezzo e quantità al tick attivo. Sottoscriviti a tick_size_change via Market WebSocket per rilevare cambiamenti.

5. Fill parziali e slippage con FAK / market order

• Sintomo: ordini market restituiscono fill parziali o sembrano cancellati.
• Perché: L'helper CLOB usa FAK (Fill-And-Kill). Se non viene completamente abbinato entro la protezione da slippage, il resto viene cancellato.
• Soluzione: Ispeziona la risposta di createMarketOrder per la quantità riempita e gestisci i fill parziali programmaticamente.

6. Rigetti legati a fee o categoria

• Sintomo: ordine fallisce con un errore relativo alle commissioni.
• Perché: Le taker fee variano per categoria (0%–1.8% attualmente); i builder possono aggiungere basis point.
• Soluzione: Conferma la categoria del mercato e le intestazioni di attribuzione se usi un Builder. Assicurati che i tuoi calcoli includano le taker fee.

H2: Operazioni CTF e errori di settlement

• Sintomo: split/merge/redeem fallisce o ritorna un errore.
• Perché: CTF è il framework ERC-1155 per i token di outcome; le operazioni possono fallire se mancano pUSD, token o se la risoluzione dell'oracolo è contestata.
• Soluzione: Verifica i saldi e che la risoluzione UMA sia completata. Se una disputa UMA mette in pausa il settlement, attendi che UMA finalizzi.

H2: Checklist di troubleshooting (runbook rapido)

• Conferma quale superficie ha segnalato l'errore (Gamma, Data, CLOB o WebSocket).
• Riproduci la richiesta minima fallita (GET order book o GET market) prima di tentare scritture.
• Controlla lo stato del wallet: proxy deployato, saldo pUSD, transazioni Relayer pendenti.
• Valida la tick size e arrotonda gli input di conseguenza.
• Per errori di paginazione, passa a after_cursor (Gamma).
• Rispetta i limiti di richiesta e applica backoff su 429/5xx.

Come ciò influisce sul tuo trading o integrazione

Gli errori che bloccano ordini aumentano le latenze e peggiorano la qualità di esecuzione. Costruisci logica client difensiva: rileva fill parziali, mostra messaggi di errore chiari agli utenti e persisti abbastanza stato per retry sicuri. Per i builder che instradano ordini attraverso il CLOB, assicurati che le intestazioni di attribuzione e la API key/HMAC siano corrette per evitare rigetti inattesi.

Chiusura

I codici di errore Polymarket di solito indicano un numero limitato di cause principali: geoblocking, paginazione/limiti di richiesta, autenticazione per il trading, stato wallet/Relayer, vincoli di tick-size e saldi insufficienti. Quando vedi un errore, identifica la superficie, cattura la risposta grezza e segui la checklist sopra. Le API pubbliche e il WebSocket di Polymarket sono le superfici diagnostiche primarie; inizia da lì.

Domande frequenti

Perché ricevo HTTP 422 da Gamma quando pagino i mercati?

Gamma usa paginazione keyset. L'API respinge offset con HTTP 422. Usa il valore after_cursor restituito dalla chiamata precedente e il parametro limit invece.

Cosa significa il geoblock 403 di Polymarket e come lo risolvo?

Un 403 di geoblock indica che il tuo IP è in una giurisdizione che Polymarket restringe per l'invio di ordini. Conferma la posizione del tuo IP e segui le linee guida ufficiali di Polymarket sull'idoneità. Non usare VPN per bypassare il blocco; contatta il supporto se pensi che sia un errore.

Il mio ordine di mercato è stato parzialmente riempito o cancellato — cosa è successo?

L'helper CLOB piazza per impostazione predefinita ordini FAK (Fill-And-Kill). Se la liquidità non ha completamente corrisposto all'ordine o la protezione da slippage si è attivata, il resto viene cancellato. Ispeziona la risposta dell'ordine per determinare la quantità riempita e ritenta con cautela.

Perché i miei ordini vengono rifiutati per gli incrementi di prezzo?

Polymarket applica una tick size (tipicamente $0.01, che si restringe a $0.001 vicino agli estremi). Se il tuo prezzo o la quantità usa un incremento più piccolo, l'ordine verrà rifiutato o arrotondato. Sottoscriviti a tick_size_change sul Market WebSocket per rimanere aggiornato.

Ho bisogno di API key per leggere order book o il Market WebSocket?

No. Le letture CLOB (order book, midpoint, price history) e il Market WebSocket sono pubbliche. Gli endpoint di trading sul CLOB richiedono API key e HMAC; le API REST Gamma e Data sono letture pubbliche.