Polymarket error codes and fixes

Esta guía explica los códigos de error más comunes que verás en la UI y en las APIs de Polymarket, por qué ocurren y pasos concretos para resolverlos. Si estás depurando una integración, el flujo de órdenes o la conexión de una wallet, esta guía te ayuda a diagnosticar el problema rápidamente.

Puntos clave

• Los errores de Polymarket se agrupan en unos pocos bloques: geobloqueo (403), validación de API (422), límites de tasa, autenticación para CLOB/trading, wallet o financiación con pUSD, y problemas con operaciones CTF.
• Para llamadas de listado en Gamma, usa paginación por cursor (after_cursor) — offset es rechazado con HTTP 422.
• El CLOB requiere API keys + HMAC para trading; las lecturas públicas no necesitan autenticación.
• Muchos casos de "orden rechazada" en la UI son causados por despliegue de wallet, pUSD insuficiente, aprobaciones, cambios de tick size o fills parciales con FAK — revisa el flujo del Relayer y la respuesta de orden del CLOB.

Por qué importan los errores (breve)

Los errores en un flujo de prediction market pueden bloquear órdenes, provocar fills parciales o paralizar la conciliación. Polymarket usa múltiples superficies (Gamma, Data, CLOB y un Market WebSocket). Saber qué superficie emitió el error acota la solución.

H2: Patrones comunes de error en API y WebSocket

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

• Síntoma: HTTP 422 al paginar mercados usando offset.
  • Por qué: Gamma usa paginación por keyset. offset es rechazado.
  • Solución: Usa after_cursor con el next_cursor devuelto por la llamada previa. Ejemplo:

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

• Síntoma: comportamiento tipo 429 (throttling) o 5xx impredecibles bajo carga.
  • Por qué: Gamma aplica límites de tasa específicos por endpoint (por ejemplo, /markets tiene un límite).
  • Solución: Respeta los límites documentados, retrocede con reintentos exponenciales y consolida solicitudes (aumenta limit hasta 1000 cuando tenga sentido).

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

• Las lecturas comunes de posiciones, trades e open interest son públicas; si ves fallos de autenticación, verifica la URL base exacta y los encabezados.

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

• Síntoma: Colocación de orden rechazada con un error de autenticación al alcanzar los endpoints de trading.
  • Por qué: Los endpoints de trading requieren una API key y una firma HMAC. Las lecturas (order book, midpoint, prices history) son públicas.
  • Solución: Genera y firma las solicitudes según la especificación del CLOB; prueba las lecturas antes de intentar escrituras.

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

• Síntoma: Conexión cerrada o sin eventos en tiempo real.
  • Por qué: El socket espera PINGs periódicos cada 10 s; los servidores pueden cerrar conexiones inactivas. Además, puedes suscribirte a un máximo de 500 instrumentos por conexión.
  • Solución: Envía PINGs según lo requerido y divide las suscripciones entre conexiones cuando superes 500 instrumentos.

H2: Geobloqueo y HTTP 403 (Polymarket geoblock 403)

• Síntoma: HTTP 403 al intentar colocar órdenes o acceder a rutas de trading; la UI muestra un mensaje de geobloqueo.
  • Por qué: Polymarket bloquea la colocación de órdenes desde ciertas jurisdicciones por IP. Algunas regiones están totalmente bloqueadas; otras son sólo close-only.
  • Solución: Confirma la ubicación de tu IP. Si estás en una jurisdicción bloqueada, sigue la orientación oficial de Polymarket sobre elegibilidad. No intentes eludir con VPN — eso viola los Terms of Service. Si crees que el bloqueo es un error, contacta al soporte de Polymarket a través del sitio oficial y proporciona diagnósticos de conexión y evidencia de IP.

H2: Motivos comunes de "orden rechazada" y soluciones

1. Wallet no desplegada o proxy ausente

• Síntoma: La orden falla durante el flujo del Relayer con un error de despliegue o proxy.
• Por qué: Polymarket soporta dos tipos de wallet; los usuarios que no usan Safe obtienen un proxy desplegado en la primera transacción.
• Solución: Deja que el Relayer complete el flujo de despliegue de la wallet. Reintenta la orden después de que la transacción se complete.

2. pUSD o tokens insuficientes

• Síntoma: Orden rechazada por saldo insuficiente.
• Por qué: Las operaciones requieren pUSD.
• Solución: Abastece tu cuenta con pUSD (ver la guía de Polymarket). Confirma el contrato del token y el saldo en tu wallet.

3. Aprobaciones ERC-20 y flujo del Relayer

• Síntoma: Intento de orden se queda esperando aprobación.
• Por qué: El Relayer puede gestionar aprobaciones sin gas, pero el flujo en la wallet debe completarse.
• Solución: Confirma que la solicitud del Relayer terminó y revisa la UI de tu wallet por confirmaciones pendientes.

4. Fallos por tick-size y incrementos mínimos

• Síntoma: Orden rechazada o redondeada inesperadamente; no se aceptan diferencias de precio pequeñas.
• Por qué: Polymarket aplica un tick size (habitualmente $0.01, que se estrecha a $0.001 cerca de extremos).
• Solución: Redondea precio y tamaño al tick activo. Suscríbete a tick_size_change via el Market WebSocket para detectar cambios.

5. FAK / fills parciales y slippage en market orders

• Síntoma: Las market orders devuelven fills parciales o parecen canceladas.
• Por qué: El helper del CLOB usa FAK (Fill-And-Kill). Si no se empareja totalmente dentro de la protección de slippage, el resto se cancela.
• Solución: Inspecciona la respuesta de createMarketOrder para la cantidad llenada y maneja fills parciales programáticamente.

6. Rechazos por tarifas o categoría

• Síntoma: Orden falla con un error relacionado con tarifas.
• Por qué: Las taker fees varían por categoría (0%–1.8% actualmente); los builders pueden añadir puntos base adicionales.
• Solución: Confirma la categoría del mercado y tus encabezados de atribución si usas un Builder. Asegura que tus cálculos incluyan las taker fees.

H2: Operaciones CTF y errores de settlement

• Síntoma: split/merge/redeem falla o devuelve un error.
• Por qué: CTF es el framework de tokens de resultado ERC-1155; las operaciones pueden fallar si no tienes pUSD, tokens, o si la resolución del oracle está disputada.
• Solución: Verifica saldos y que la resolución de UMA se haya completado. Si UMA ha pausado el settlement por disputas, espera hasta que UMA finalice.

H2: Checklist de troubleshooting (runbook rápido)

• Confirma qué superficie reportó el error (Gamma, Data, CLOB o WebSocket).
• Reproduce la petición mínima que falla (GET order book o GET market) antes de intentar escrituras.
• Revisa el estado de la wallet: proxy desplegado, saldo pUSD, transacciones pendientes del Relayer.
• Valida el tick size y redondea las entradas en consecuencia.
• Para errores de paginación, cambia a after_cursor (Gamma).
• Respeta los límites de tasa y retrocede ante 429/5xx.

Cómo afecta esto a tu trading o integración

Los errores que bloquean órdenes aumentan la latencia y empeoran la calidad de ejecución. Construye lógica cliente defensiva: detecta fills parciales, muestra mensajes de error claros a los usuarios y persiste suficiente estado para reintentos seguros. Para builders que enrutan órdenes a través del CLOB, asegura que tus encabezados de atribución y la API key/HMAC sean correctos para evitar rechazos inesperados.

Cierre

Los códigos de error de Polymarket suelen apuntar a un pequeño número de causas raíz: geobloqueo, paginación/límites de tasa, autenticación para trading, estado de wallet/Relayer, restricciones de tick-size y saldos insuficientes. Cuando veas un error, identifica la superficie, captura la respuesta cruda y sigue el checklist anterior. Las APIs públicas y el WebSocket de Polymarket son las superficies de diagnóstico principales; empieza por ahí.

Preguntas frecuentes

¿Por qué recibo HTTP 422 de Gamma al paginar mercados?

Gamma usa paginación por keyset. La API rechaza offset con HTTP 422. Usa el valor after_cursor devuelto por la llamada previa y el parámetro limit en su lugar.

¿Qué significa el geobloqueo 403 de Polymarket y cómo lo soluciono?

Un 403 por geobloqueo indica que tu IP está en una jurisdicción que Polymarket restringe para la colocación de órdenes. Confirma la ubicación de tu IP y sigue la guía oficial de elegibilidad de Polymarket. No uses VPNs para evadir el bloqueo; contacta al soporte si crees que es un error.

Mi market order se llenó parcialmente o se canceló — ¿qué pasó?

El helper del CLOB coloca por defecto órdenes FAK (Fill-And-Kill). Si la liquidez no llenó la orden por completo o se activó la protección de slippage, el resto se cancela. Inspecciona la respuesta de la orden para determinar la cantidad llenada y reintenta con cautela.

¿Por qué se rechazan mis órdenes por incrementos de precio?

Polymarket aplica un tick size (típicamente $0.01, que se estrecha a $0.001 cerca de extremos). Si tu precio o cantidad usa un incremento menor, la orden será rechazada o redondeada. Suscríbete a tick_size_change en el Market WebSocket para mantenerte actualizado.

¿Necesito API keys para leer order books o para el Market WebSocket?

No. Las lecturas del CLOB (order book, midpoint, price history) y el Market WebSocket son públicas. Los endpoints de trading del CLOB requieren una API key y HMAC; las REST APIs Gamma y Data son lecturas públicas.