Errores de la API de Polymarket: cada código, explicado

Todos los errores de la API CLOB de Polymarket vuelven con la misma forma (un objeto JSON con un único campo error), lo que es admirablemente coherente y no sirve de nada cuando intentas averiguar por qué tu orden acaba de desaparecer.

{
  "error": "<message>"
}

Esta página los explica. Cubre los errores documentados del CLOB, los códigos de estado y sus causas reales y, la parte que no encontrarás en la documentación oficial, los errores con los que la gente se topa en producción y que Polymarket nunca ha puesto por escrito.

Cada mensaje documentado tiene además su propia página con causas y un veredicto sobre si reintentar, recogidas en el índice de errores de Polymarket.

Referencia rápida de códigos de estado

401: errores de autenticación

Unauthorized/Invalid api key

El error de Polymarket más buscado. Tu clave de API falta, ha caducado o no es válida. En la práctica casi nunca es una clave realmente mala; es una de estas causas:

1. Solo envías parte del conjunto de credenciales. La autenticación L2 de Polymarket necesita la key, el secret y la passphrase juntos. Un fallo habitual es rellenar POLY_API_KEY y POLY_PASSPHRASE pero dejar el secret sin definir: el cliente envía una solicitud bien formada pero imposible de firmar.
2. El reloj de tu sistema se ha desfasado. La firma incluye una marca de tiempo, y un reloj desfasado más de unos segundos produce una firma que el servidor rechaza como no válida. Es la causa que la gente encuentra la última y es tristemente común en VMs y contenedores.
3. Derivaste la clave con una wallet distinta de la que usas para operar. Las claves están vinculadas a la dirección de firmante que las creó.
4. Llamas a un endpoint autenticado con cabeceras L1 donde se esperan L2, o al revés.

Invalid L1 Request headers

Tus cabeceras de autenticación L1 (el conjunto de firma EIP-712) están mal formadas, o la firma no coincide con la dirección que dices ser. Comprueba que firmas con la misma clave privada que la dirección de la cabecera y que tu domain separator coincide con la cadena en la que estás (Polygon, chain ID 137). Una firma válida para otro chain ID sigue siendo una firma válida, solo que no para este servidor.

Could not create api key / Could not derive api key!

Son los errores detrás de la búsqueda "polymarket unable to generate api credentials". Los dos los devuelven los endpoints de autenticación cuando falla la creación o la derivación de la clave. Could not derive api key! en GET /auth/derive-api-key suele significar que aún no existe ninguna clave para ese firmante: derive devuelve una clave existente, no crea una. Crea primero la clave con POST /auth/api-key y derívala en las ejecuciones posteriores.

400: errores de rechazo de órdenes

Se devuelven cuando una orden pasa la validación de transporte pero incumple las reglas de negocio. Aparecen en el cuerpo de la respuesta de POST /order y POST /orders.

425: Too Early

Un código de estado poco habitual que confunde a la gente porque apenas se usa en el resto de la web. En Polymarket significa que el motor de matching se está reiniciando. Tu solicitud llegó durante la ventana en la que el exchange vuelve a arrancar.

Este es de verdad transitorio y de verdad seguro de reintentar: probablemente sea el error de la plataforma más apropiado para reintentar. Espera y vuelve a intentarlo; no lo trates como un fallo y no alertes por un caso aislado.

503: el exchange está en un modo restringido

Polymarket puede poner el exchange en modos restringidos. No son fallos de tu lado, y por mucho que reintentes la misma solicitud no servirá de nada hasta que se levante el modo.

El modo post-only es el que hay que gestionar bien, porque te dice exactamente cuándo volver. La respuesta incluye code: "post_only_mode" y retry_after_seconds, y el mismo retraso se envía en la cabecera Retry-After.

{
  "error": "post-only mode: only post-only orders and cancels are allowed",
  "code": "post_only_mode",
  "retry_after_seconds": 79
}

Errores que no están en la documentación

Aquí es donde se va la mayor parte del tiempo real de depuración. Los siguientes no aparecen en la referencia de códigos de error de Polymarket porque no los genera la aplicación CLOB: vienen del edge, de la red o de tu biblioteca cliente. Saber qué capa produjo un error te dice dónde buscar.

"The server was unable to process your request"

El error de Polymarket más buscado que no está en la documentación. Es un mensaje de la capa de edge, no un error de la API CLOB: es lo que recibes cuando la solicitud nunca llegó a la aplicación, o nunca volvió de ella de forma limpia. En la práctica, las causas habituales son:

• Una solicitud mal formada que el edge rechaza antes de enrutarla: un payload demasiado grande, una cabecera incorrecta o un método HTTP no válido para la ruta.
• Un fallo transitorio aguas arriba mientras el servicio se vuelve a desplegar o está bajo carga.
• Limitación de tasa sostenida. Como Cloudflare limita poniendo en cola en lugar de rechazar, un cliente muy por encima del límite puede acabar con solicitudes que agotan el tiempo en el edge en lugar de devolver un 429 limpio.

Trátalo como reintentable con backoff, pero si es persistente y no ocasional, comprueba primero tu tasa de solicitudes (consulta la referencia de límites de tasa) y después el tamaño de tu payload.

403 Forbidden

Un 403 de Polymarket normalmente no es un problema de autenticación, y eso es lo que lo hace confuso. Por lo general es el edge bloqueando la solicitud. Los desencadenantes comunes son las restricciones geográficas en los endpoints de trading, los rangos de IP de centros de datos y VPN sometidos a verificación, y la falta de cabeceras (o cabeceras poco parecidas a las de un navegador) en solicitudes que el edge espera que vengan de un cliente.

Si un 403 aparece solo desde tu VM en la nube y no desde tu portátil, es un problema de reputación de la IP, no del código. Si aparece en los endpoints de trading pero no en los de datos de mercado, es geográfico.

Errores de SSL, TLS y certificados

"polymarket ssl error", "polymarket certificate error" y "polymarket https error" son casi siempre del lado del cliente. Los certificados de Polymarket están bien; lo que falla es algo entre tú y ellos. Comprueba, por orden: un bundle de CA desactualizado (muy común en imágenes Docker antiguas y entornos Python congelados), un proxy corporativo que inspecciona TLS y sustituye el certificado por el suyo, y un reloj del sistema tan desfasado que los certificados parecen aún no válidos o caducados.

# 1. Does TLS work at all, outside your app's HTTP client?
curl -sS -o /dev/null -w "%{http_code} %{ssl_verify_result}\n" \
  https://clob.polymarket.com/ok

# 2. Is your CA bundle current? (Python)
python3 -c "import certifi, os; print(certifi.where()); print(os.path.getmtime(certifi.where()))"

# 3. Is your clock right? Certificate validation depends on it.
date -u

"Service not ready"

Un mensaje de estado de arranque: el servicio está lo bastante levantado para responder, pero no listo para servir. En la práctica trátalo como un 425: espera y reintenta. Debería resolverse en segundos, y no es algo que puedas arreglar desde el cliente.

"Order manager not ready"

Un mensaje de estado de arranque del motor de matching, pariente cercano de 425 Too Early. El servicio es accesible, pero la capa de gestión de órdenes no ha terminado de arrancar, así que aceptará tu conexión y rechazará tu orden. Es transitorio y seguro de reintentar con backoff, pero tómalo como una señal para dejar de enviar durante unos segundos en lugar de insistir, porque un reinicio suele significar que el libro está a punto de cambiar bajo tus pies.

Si lo ves de forma persistente y no en ráfagas, revisa el estado de Polymarket antes de depurar tu propio código: no hay nada que arreglar del lado del cliente.

"Couldn't get a quote"

Suele significar que no hay liquidez en reposo en el lado al que pediste precio, no que algo esté roto. En los mercados Up/Down poco líquidos cerca del vencimiento, un lado se vacía con frecuencia (nadie vende Up a ningún precio cuando Up es seguro), así que una solicitud de cotización no devuelve nada. Nuestros propios datos muestran que es habitual: en una muestra de mercados BTC de 5 minutos, 1,454 de 8,510 tenían el libro de asks vacío en un lado 60 segundos antes del vencimiento.

Trátalo como “no hay mercado” y no como un error: omite la operación y no reintentes en un bucle cerrado. Si necesitas saber con qué frecuencia ocurre en una serie que operas, las páginas de datos de mercado muestran la liquidez por intervalo.

Excepciones de la biblioteca cliente

Errores como PolyApiException[status_code=None, error_message=request exception!] vienen del cliente de Python, no del servidor. status_code=None es la pista: nunca se recibió ninguna respuesta HTTP, así que es un fallo a nivel de conexión (DNS, TLS, timeout o un socket caído) que aparece como una excepción de la biblioteca. Depúralo como un problema de red, no de la API. El mismo razonamiento se aplica a BuilderApiKeyCreds invalid authorization 401 en el cliente del relayer, que significa que no se aceptaron las credenciales de builder pasadas al cliente; vuelve a derivarlas en lugar de reutilizar un conjunto en caché.

Una política de reintentos que lo gestiona todo

La conclusión práctica es que los errores de Polymarket se dividen en tres grupos, y mezclarlos es lo que hace frágiles a los bots: reintentar sin más, reintentar tras un retraso concreto y no reintentar nunca.

type Decision =
  | { retry: true; delayMs: number }
  | { retry: false; reason: string };

function classify(status: number, body: { error?: string; code?: string; retry_after_seconds?: number }, attempt: number): Decision {
  const msg = (body.error ?? "").toLowerCase();
  const backoff = Math.min(2 ** attempt * 250, 8000);
  const jittered = Math.random() * backoff;

  // Never retry — the request itself is wrong.
  if (status === 401) return { retry: false, reason: "auth: check key, secret, passphrase and clock drift" };
  if (status === 404) return { retry: false, reason: "not found" };
  if (status === 400) return { retry: false, reason: `validation: ${body.error}` };

  // Mode-restricted — the server tells you when to come back.
  if (status === 503 && body.code === "post_only_mode") {
    return { retry: true, delayMs: (body.retry_after_seconds ?? 60) * 1000 };
  }
  if (status === 503) return { retry: false, reason: "exchange paused or cancel-only" };

  // Transient — safe to retry.
  if (status === 425 || status === 429 || status >= 500) return { retry: true, delayMs: jittered };
  if (msg.includes("service not ready")) return { retry: true, delayMs: jittered };

  return { retry: false, reason: `unhandled status ${status}` };
}

Errores de los que no puedes salir depurando

Algunas cosas que parecen errores simplemente no están soportadas. Polymarket no tiene un endpoint de libro de órdenes histórico, así que no hay nada a lo que llamar mal. El libro de un mercado resuelto devuelve 404 porque Polymarket deja de servirlo cuando el mercado se liquida, aunque tu ID de token sea correcto.

Si te estás topando con esos muros, no estás depurando una integración: te falta una fuente de datos. PolyTest graba snapshots puntuales de los mercados cripto Up/Down de Polymarket mientras están activos, con la profundidad completa del libro de órdenes, así que el historial sigue ahí después de la resolución. Nuestra propia referencia de errores cubre las formas de error de la API de PolyTest, que en comparación son deliberadamente aburridas.