¿Usas OPenClaw y te encuentras con fallos en la API o tiempos de espera? Este artículo recopila los errores más comunes y sus soluciones prácticas para que puedas retomar tu trabajo rápidamente, sin quedarte mirando la pantalla sin saber qué hacer.
Error 401 No autorizado: revisa la clave y los permisos
Un error 401 generalmente significa que la solicitud carece de credenciales válidas. Primero verifica que tu clave de API esté correctamente pegada en las variables de entorno o en el archivo de configuración, asegurándote de que no tenga espacios extra ni saltos de línea al inicio o al final. Si copiaste la clave directamente desde la consola, te recomendamos escribirla manualmente otra vez; muchos problemas surgen por caracteres que se pierden al copiar. Además, algunos modelos o endpoints requieren permisos adicionales: revisa en el panel de desarrollador que la opción "Permitir acceso" esté marcada.
Límite de frecuencia 429: ajusta el intervalo de llamadas y la cuota
Enviar demasiadas solicitudes en poco tiempo dispara la limitación de tasa y devuelve el código 429. No intentes reintentar ciegamente; primero pausa de 5 a 10 segundos y luego reintenta con una estrategia de backoff exponencial. Puedes implementar una cola de solicitudes o agregar un mecanismo de sleep para no superar el límite de velocidad. Si el problema aparece con frecuencia, comprueba si tu cuenta está en período de prueba (los límites suelen ser más bajos). Mejorar el plan o solicitar un aumento de cuota lo soluciona de raíz. También verifica si otras aplicaciones están usando la misma clave de API; compartir clave puede hacer que se alcance fácilmente el umbral de limitación.
Tiempo de espera agotado o Socket Hang Up: revisa la red y el proxy
Los errores "Connection Timeout" o "Socket Hang Up" suelen deberse a una red inestable o a una configuración incorrecta del proxy. Primero prueba si puedes acceder directamente al servidor oficial de OPenClaw con comandos como ping o curl para medir la latencia. Si usas un proxy, confirma que el protocolo y el puerto sean correctos y que el proxy no esté bloqueando el tráfico. Algunas redes corporativas bloquean puertos no estándar; cambiar al puerto HTTPS (443) puede evitar ciertas restricciones. Además, un tiempo de espera demasiado corto puede provocar falsos positivos: prueba aumentar el parámetro de timeout de 10 segundos (valor por defecto) a 30 segundos.
Error 500 interno del servidor: prioriza la verificación del formato del cuerpo de la solicitud
Cuando el servidor devuelve un error 500, no asumas que el servidor se ha caído; lo más probable es que el formato de tu solicitud sea incorrecto. Revisa si el JSON es válido, si los nombres de los campos están escritos correctamente (por ejemplo, "model" en lugar de "module"). Presta especial atención a los valores booleanos y numéricos: no deben llevar comillas. Por ejemplo, "temperature": true romperá la petición. Si el cuerpo de la solicitud es muy grande, intenta dividirlo en fragmentos más pequeños. También verifica si el array de mensajes contiene roles no compatibles (por ejemplo, si usaste el rol "function" sin que el modelo lo soporte).
Error 403 Permiso denegado: estado de la cuenta y restricciones geográficas
Un error 403 puede indicar que la cuenta está bloqueada o que hay restricciones geográficas. Primero inicia sesión en el sitio web de OPenClaw para comprobar el estado de tu cuenta: busca notificaciones de saldo pendiente o infracciones. Algunos modelos solo están disponibles en regiones específicas. Si usas una IP de una zona no compatible, cambia de nodo o activa el modo global. Además, ciertas cuentas de prueba gratuita ven reducir sus permisos con el tiempo; renovar o actualizar a un plan de pago suele resolver el error 403.
