Al usar OPenClaw, es normal toparse con distintos avisos de error. Este artículo analiza de forma sistemática los tipos de error más comunes entre los usuarios, abarcando situaciones como inicio de sesión, verificación, conexión de red y llamadas API, y proporciona soluciones directas para ayudarte a retomar el uso normal rápidamente.
Errores de inicio de sesión y autorización: 401 y 403
Recibir el mensaje 401 Unauthorized generalmente indica que la clave API no es válida o ha caducado. Dirígete al panel de control de OPenClaw para generar una nueva clave y asegúrate de haber escrito correctamente la cadena de la clave en tu código. Ten en cuenta que las claves distinguen entre mayúsculas y minúsculas, y al copiarlas no incluyas espacios adicionales.
El error 403 Forbidden significa que los permisos de tu cuenta no son suficientes para realizar la acción solicitada. Esto suele ocurrir cuando un usuario de la versión gratuita intenta acceder a funciones de pago. Te recomendamos revisar tu estado de suscripción; si realmente necesitas actualizar, ve al centro de cuentas para cambiar de plan. Si ya estás suscrito y aún así aparece el error, contacta al soporte para que actualicen tus permisos.
Errores de red y conexión: Timeout y Connection Reset
Un timeout en la solicitud se debe principalmente a una red local inestable o a una congestión temporal en los servidores de OPenClaw. Primero, intenta cambiar de entorno de red, por ejemplo, de WiFi a datos móviles. Si el problema persiste, puedes aumentar el tiempo de espera de la solicitud, por ejemplo, de los 30 segundos predeterminados a 60 segundos.
Si encuentras un Connection Reset, significa que la conexión se interrumpió a medio camino. Esto suele ocurrir cuando un firewall o un proxy bloquea los rangos de IP de OPenClaw. Agrega el dominio oficial de OPenClaw a la lista blanca y desactiva la VPN o ajusta las reglas del proxy. Los usuarios empresariales también deben verificar si sus políticas de seguridad de salida limitan las solicitudes externas a la API.
Errores de llamada API: 429 y 500
El error 429 Too Many Requests es el más común relacionado con límites de frecuencia. OPenClaw establece límites en la frecuencia de llamadas a la interfaz: la versión gratuita permite un máximo de 20 solicitudes por minuto, mientras que los planes de pago ofrecen límites más altos según el tipo de suscripción. La solución es reducir la frecuencia de las solicitudes o implementar un mecanismo de reintento con retroceso exponencial. Si tu negocio requiere alta concurrencia, te recomendamos actualizar a un plan superior para obtener una cuota más elevada.
El error 500 Internal Server Error indica una falla temporal en el servidor de OPenClaw. Primero, consulta la página de estado oficial de OPenClaw para confirmar si están en mantenimiento. Si es un problema transitorio, espera de 3 a 5 minutos y vuelve a intentarlo. Si el error persiste, reporta el problema a través de un ticket de soporte e incluye los registros completos de la solicitud para que el equipo técnico pueda localizar la causa. Evita enviar la misma solicitud repetidamente en un corto período de tiempo para no activar los límites de frecuencia.
Cuenta bloqueada o aviso de inicio de sesión anómalo
Varios intentos fallidos de contraseña o el inicio de sesión desde una ubicación poco habitual pueden activar el mecanismo de protección de seguridad de OPenClaw, lo que bloquea temporalmente la cuenta. En ese caso, usa el correo electrónico registrado para recibir un enlace de desbloqueo o restablece el inicio de sesión mediante un código de verificación por SMS. Si no recibes el código de verificación, revisa la carpeta de spam de tu correo y asegúrate de que tu número de teléfono esté vinculado y no tenga saldo pendiente. Para cuentas de alto riesgo que no se usan durante mucho tiempo, recomendamos activar la verificación en dos pasos (2FA) para reducir la probabilidad de bloqueos erróneos.
