Codes d'erreur Polymarket et corrections

Ce guide explique les codes d'erreur Polymarket les plus courants que vous verrez dans l'interface et les APIs, pourquoi ils surviennent et les étapes concrètes pour les résoudre. Si vous déboguez une intégration, un flux d'ordre ou une connexion de portefeuille, ce guide vous aide à diagnostiquer rapidement le problème.

Points clés

• Les erreurs Polymarket se répartissent en quelques catégories : géoblocage (403), validation d'API (422), limites de débit, authentification CLOB/trading, portefeuille ou financement pUSD, et problèmes d'opérations CTF.
• Pour les appels de listing Gamma, utilisez la pagination par curseur (after_cursor) — offset est rejeté avec HTTP 422.
• Le CLOB exige des clés API + HMAC pour le trading ; les lectures publiques n'ont pas besoin d'auth.
• Beaucoup de cas d'« order rejected » dans l'UI proviennent d'un déploiement de portefeuille, d'un solde pUSD insuffisant, d'approbations manquantes, de changements de tick-size ou de remplissages partiels FAK — vérifiez le flux Relayer et la réponse de l'ordre CLOB.

Pourquoi les erreurs comptent (bref)

Les erreurs dans un flux de marché prédictif peuvent bloquer des ordres, provoquer des remplissages partiels ou retarder la réconciliation. Polymarket utilise plusieurs surfaces (Gamma, Data, CLOB et un Market WebSocket). Savoir quelle surface a généré l'erreur réduit le champ des correctifs.

H2: Modèles d'erreurs courants pour les API et WebSocket

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

• Symptôme : HTTP 422 lors de la pagination des marchés en utilisant offset.
  • Pourquoi : Gamma utilise la pagination par keyset. offset est rejeté.
  • Correction : Utilisez after_cursor avec le next_cursor retourné par l'appel précédent. Exemple :

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

• Symptôme : comportement de type 429 (throttling) ou 5xx imprévisibles sous charge.
  • Pourquoi : Gamma applique des limites de débit spécifiques par endpoint (par exemple /markets a une limite).
  • Correction : Respectez les limites documentées, effectuez un backoff exponentiel et consolidez les requêtes (augmentez limit jusqu'à 1000 lorsque c'est pertinent).

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

• Les lectures courantes pour positions, trades et open interest sont publiques ; si vous observez des échecs d'auth, vérifiez l'URL de base exacte et les en-têtes.

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

• Symptôme : placement d'ordre rejeté avec une erreur d'authentification lors des appels de trading.
  • Pourquoi : Les endpoints de trading requièrent une clé API et une signature HMAC. Les lectures (order book, midpoint, prices history) sont publiques.
  • Correction : Générez et signez les requêtes selon la spécification CLOB ; testez d'abord les lectures avant d'essayer des écritures.

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

• Symptôme : connexion fermée ou absence d'événements en temps réel.
  • Pourquoi : le socket attend des PING périodiques toutes les 10 s ; les serveurs peuvent fermer les connexions inactives. De plus, vous pouvez vous abonner à au maximum 500 instruments par connexion.
  • Correction : Envoyez les PING requis et répartissez les abonnements sur plusieurs connexions si vous dépassez 500 instruments.

H2: Géoblocage et HTTP 403 (Polymarket geoblock 403)

• Symptôme : HTTP 403 lors d'une tentative de placement d'ordres ou d'accès aux routes de trading ; l'UI renvoie un message de géoblocage.
  • Pourquoi : Polymarket bloque le placement d'ordres depuis certaines juridictions en fonction de l'IP. Certaines régions sont totalement bloquées ; d'autres sont en mode fermeture-only (close-only).
  • Correction : Confirmez l'emplacement de votre IP. Si vous êtes dans une juridiction bloquée, suivez les indications officielles de Polymarket concernant l'éligibilité. N'essayez pas de contourner le blocage avec un VPN — cela viole les Conditions d'utilisation. Si vous pensez qu'il s'agit d'une erreur, contactez le support Polymarket via le site officiel et fournissez des diagnostics de connexion et une preuve d'IP.

H2: Raisons courantes d'« order rejected » et corrections

1. Portefeuille non déployé ou proxy manquant

• Symptôme : l'ordre échoue pendant le flux Relayer avec une erreur de déploiement ou de proxy.
• Pourquoi : Polymarket prend en charge deux types de portefeuilles ; les utilisateurs non-Safe obtiennent un proxy déployé lors de la première transaction.
• Correction : Laissez le Relayer terminer le flux de déploiement du portefeuille. Retentez l'ordre après la confirmation de la transaction.

2. pUSD insuffisant ou tokens manquants

• Symptôme : ordre rejeté pour solde insuffisant.
• Pourquoi : Les échanges nécessitent du pUSD.
• Correction : Approvisionnez votre compte en pUSD (voir les indications de Polymarket). Vérifiez le contrat du token et le solde dans votre portefeuille.

3. Approbations ERC-20 et flux Relayer

• Symptôme : tentative d'ordre bloquée en attente d'approbation.
• Pourquoi : Le Relayer peut gérer les approbations sans frais de gas, mais le flux du portefeuille doit être complété.
• Correction : Confirmez que la requête Relayer s'est bien déroulée et vérifiez l'UI de votre portefeuille pour d'éventuelles confirmations en attente.

4. Échecs liés au tick-size et aux incréments minimums

• Symptôme : ordre rejeté ou arrondi inattendu ; de petites différences de prix ne sont pas acceptées.
• Pourquoi : Polymarket applique un tick size (généralement $0.01, se resserrant à $0.001 près des extrêmes).
• Correction : Arrondissez le prix et la taille au tick actif. Abonnez-vous à tick_size_change via le Market WebSocket pour détecter les changements.

5. FAK / remplissages partiels et slippage des ordres market

• Symptôme : les ordres market retournent des remplissages partiels ou semblent annulés.
• Pourquoi : l'assistant CLOB utilise FAK (Fill-And-Kill). Si l'ordre n'est pas entièrement apparié dans la fenêtre de slippage, le reste est annulé.
• Correction : Inspectez la réponse de createMarketOrder pour la quantité remplie et gérez les remplissages partiels par programme.

6. Rejets liés aux frais ou à la catégorie

• Symptôme : l'ordre échoue avec une erreur liée aux frais.
• Pourquoi : les taker fees varient selon la catégorie (0 %–1.8 % actuellement) ; les builders peuvent appliquer des points de base supplémentaires.
• Correction : Confirmez la catégorie du marché et vos en-têtes d'attribution si vous utilisez un Builder. Assurez-vous d'inclure les taker fees dans vos calculs de coût.

H2: Opérations CTF et erreurs de règlement

• Symptôme : split/merge/redeem échoue ou renvoie une erreur.
• Pourquoi : CTF est le framework d'ERC-1155 pour les tokens de résultat ; les opérations peuvent échouer si vous n'avez pas de pUSD, de tokens ou si la résolution oracle est contestée.
• Correction : Vérifiez les soldes et que la résolution UMA est terminée. Si une dispute UMA met le règlement en pause, attendez la finalisation d'UMA.

H2: Checklist de dépannage (runbook rapide)

• Confirmez quelle surface a rapporté l'erreur (Gamma, Data, CLOB ou WebSocket).
• Reproduisez la requête minimale qui échoue (GET order book ou GET market) avant d'essayer des écritures.
• Vérifiez l'état du portefeuille : proxy déployé, solde pUSD, transactions Relayer en attente.
• Validez le tick size et arrondissez les entrées en conséquence.
• Pour les erreurs de pagination, basculez sur after_cursor (Gamma).
• Respectez les limites de débit et effectuez un backoff sur 429/5xx.

Comment cela affecte votre trading ou intégration

Les erreurs qui bloquent des ordres augmentent la latence et détériorent la qualité d'exécution. Implémentez une logique cliente défensive : détectez les remplissages partiels, affichez des messages d'erreur clairs aux utilisateurs et persistez suffisamment d'état pour des tentatives de nouvelle exécution sûres. Pour les builders qui routent des ordres via le CLOB, assurez-vous que vos en-têtes d'attribution et votre clé API/HMAC sont corrects pour éviter des rejets inattendus.

Conclusion

Les codes d'erreur Polymarket renvoient généralement à un petit nombre de causes racines : géoblocage, pagination/limites de débit, authentification pour le trading, état du portefeuille/Relayer, contraintes de tick-size et soldes insuffisants. Quand vous voyez une erreur, identifiez la surface, capturez la réponse brute et suivez la checklist ci-dessus. Les APIs publiques et le WebSocket de Polymarket sont les surfaces de diagnostic principales ; commencez par là.

Foire aux questions

Pourquoi reçois‑je HTTP 422 de Gamma lors de la pagination des marchés ?

Gamma utilise la pagination par keyset. L'API rejette offset avec HTTP 422. Utilisez la valeur after_cursor retournée par l'appel précédent et le paramètre limit à la place.

Que signifie Polymarket geoblock 403 et comment le corriger ?

Un 403 de géoblocage indique que votre IP se trouve dans une juridiction que Polymarket restreint pour le placement d'ordres. Confirmez l'emplacement de votre IP et suivez les indications officielles d'éligibilité de Polymarket. N'utilisez pas de VPN pour contourner le blocage ; contactez le support si vous pensez qu'il s'agit d'une erreur.

Mon ordre market a été partiellement rempli ou annulé — que s'est‑il passé ?

L'assistant CLOB place par défaut des ordres FAK (Fill-And-Kill). Si la liquidité n'a pas entièrement apparié l'ordre ou si la protection contre le slippage a été déclenchée, le reste est annulé. Inspectez la réponse de l'ordre pour déterminer la quantité remplie et retentez prudemment.

Pourquoi mes ordres sont‑ils rejetés pour incréments de prix ?

Polymarket applique un tick size (typiquement $0.01, se resserrant à $0.001 près des extrêmes). Si votre prix ou votre quantité utilise un incrément plus petit, l'ordre sera rejeté ou arrondi. Abonnez‑vous à tick_size_change sur le Market WebSocket pour rester à jour.

Ai‑je besoin de clés API pour lire les order books ou le Market WebSocket ?

Non. Les lectures CLOB (order book, midpoint, price history) et le Market WebSocket sont publics. Les endpoints de trading sur le CLOB requièrent une clé API et un HMAC ; les REST APIs Gamma et Data sont des lectures publiques.