Error 429 en OpenClaw: cuándo esperar y cómo recuperar la tarea

Ante Rate limit exceeded o un HTTP 429 en OpenClaw, pausa las nuevas solicitudes y comprueba qué servicio lo devuelve. Un límite temporal del modelo exige reducir la presión y respetar el tiempo de espera. Una cuota diaria, semanal o mensual agotada necesita su renovación o una alternativa con acceso disponible. Un 429 al instalar una habilidad de ClawHub afecta al registro de descargas, no demuestra que el modelo haya agotado sus tokens.

Si OpenClaw ya muestra que está reintentando, deja trabajar a esa recuperación acotada: reenviar la petición desde otra ventana añade tráfico y puede repetir acciones que ya terminaron. Guarda los resultados comprobados y continúa únicamente el paso pendiente cuando el acceso se recupere.

Los procedimientos siguientes se basan en la documentación consultada el 5 de octubre de 2026. Los comandos se presentan para diagnóstico; no se ha reproducido el error con credenciales reales ni realizado llamadas de pago para esta guía.

Identifica quién devuelve el 429 antes de cambiar nada

Busca el mensaje completo, la hora y la operación rechazada. La palabra «límite» no basta para decidir cuánto esperar.

En el equipo del Gateway, consulta un intervalo limitado de registros y el agente afectado:

openclaw logs --limit 200 --max-bytes 250000 --plain
openclaw models status --agent main

Sustituye main por tu agente. Si utilizas un perfil de instalación distinto, selecciónalo también en el comando, por ejemplo openclaw --profile work logs --limit 200 --plain. La referencia actual de registros utiliza archivos rotativos por fecha y perfil; no hay que asumir una ruta de archivo fija para todas las instalaciones.

Dentro de la conversación que falla, consulta por separado:

/model status
/status

Anota el modelo seleccionado y el que realmente intentó responder, el perfil sin sus secretos, el código o motivo, el tiempo de espera y cualquier alternativa intentada. El estado del agente no muestra por sí solo la selección específica del chat. Además, models status sin --probe comprueba configuración y estado de acceso, no una respuesta del modelo. Puede resolver secretos configurados: no publiques su salida completa. Estas diferencias están en la CLI de modelos.

Si el motivo resulta ser 401, utiliza el diagnóstico de autenticación de OpenClaw. Renovar el token del Gateway por un límite del proveedor no trata la causa.

Cuánto esperar: sigue el límite real, no un minuto universal

Espera al menos el plazo válido que indique el proveedor para un rechazo temporal. Si no hay plazo, deja que OpenClaw aplique su espera creciente y reduce las fuentes que generan peticiones. No conviertas cualquier 429 en un bucle de intentos cada pocos segundos.

La decisión cambia según el motivo:

La política de reintentos de OpenClaw permite hasta diez intentos en total para recuperar una petición rechazada por un límite temporal del modelo. La espera aumenta con una pequeña variación aleatoria; un plazo del proveedor establece el mínimo, incluso si supera los 30 segundos del tope ordinario de espera creciente. Cancelar o alcanzar el plazo final de la ejecución detiene la recuperación.

Los diez intentos son un máximo del mecanismo, no una instrucción para pulsar diez veces «enviar». Tampoco debes interpretar los 90 segundos documentados para otros fallos transitorios como el tiempo de renovación de todos los 429. Las ventanas periódicas agotadas pasan directamente a una alternativa apta cuando la política lo permite. Una cabecera Retry-After, por sí sola, no demuestra que se haya agotado una ventana periódica.

Si el proveedor es OpenAI

Revisa las restricciones de la organización, del proyecto y del modelo que realmente recibe la llamada. Las peticiones por minuto y los tokens por minuto son límites distintos; también hay ventanas más largas y familias que comparten capacidad. Crear otra clave del mismo proyecto o cambiar a un modelo de la misma familia puede conservar el mismo límite. Véase la guía oficial de límites de OpenAI.

El código slow_down identifica un aumento demasiado rápido del tráfico y puede aparecer incluso sin superar los límites nominales de peticiones o tokens por minuto. Reduce la carga y vuelve a aumentarla gradualmente. Un 503 con server_is_overloaded describe otra condición: comprueba el código, además del mensaje.

También importa distinguir una alerta de gasto de un límite estricto: la alerta avisa y permite continuar; un límite estricto aplicado rechaza las peticiones afectadas con 429. Cuando ese es el motivo, repetir no cambia el control de gasto. Si vas a consultar la consola, comprueba el mismo proyecto y organización del acceso seleccionado, no solo que otra cuenta tenga saldo.

Si el proveedor es Anthropic

Un rate_limit_error puede indicar frecuencia, el tope mensual del nivel de uso o un límite de gasto del espacio de trabajo de Claude Code. Según la referencia de errores de Claude, un 429 por el tope de gasto del nivel puede carecer de retry-after y continúa fallando hasta recuperar acceso. No deduzcas de la ausencia de cabecera que conviene reintentar inmediatamente.

Por qué todos los perfiles siguen en espera después de reiniciar

Reiniciar el Gateway no borra el estado persistente de espera ni renueva la cuota del proveedor. OpenClaw guarda cooldownUntil y disabledUntil en el estado SQLite de autenticación del agente. Por eso puedes volver a ver los mismos perfiles no disponibles después de reiniciar. La documentación de recuperación y perfiles explica estos estados.

Consulta openclaw models status --agent main y busca Unavailable auth profiles; la salida JSON incluye auth.unusableProfiles. Lee el motivo y el plazo, si están disponibles. El mensaje de agotamiento puede indicar el vencimiento más próximo relevante, pero eso significa que podrá volver a considerarse un candidato: no garantiza que el proveedor ya admita la solicitud.

Hay dos alcances importantes:

• Un límite de frecuencia puede estar asociado al modelo mediante cooldownModel. Otro modelo del mismo proveedor podría ser apto si tiene capacidad distinta.
• Un bloqueo por facturación afecta al perfil completo entre modelos. Cambiar solo el modelo de ese perfil no elimina el motivo.

Las esperas ordinarias documentadas crecen de 30 segundos a un minuto y después a cinco minutos; los bloqueos iniciales por facturación duran diez minutos. Son decisiones internas de OpenClaw, no la renovación prometida de tu límite externo. Recargar saldo tampoco elimina automáticamente un plazo persistente que ya estaba activo. El controlador contempla comprobaciones limitadas del principal para recuperar acceso, sin necesitar un reinicio como rutina.

Existe además una caché opcional de fallos de autenticación que vive solo en el proceso y sí desaparece al reiniciar. Esa excepción no convierte el reinicio en una limpieza general de cuotas o esperas. No edites SQLite ni borres perfiles para forzar nuevos intentos: conserva el motivo y corrige la condición correspondiente.

Por qué no entra el modelo de reserva que ya configuraste

Comprueba primero si la selección permite usarlo. En la política actual, una selección explícita mediante /model, el selector de modelos o una sustitución puntual es estricta: puede mostrar el fallo del modelo elegido aunque exista una lista predeterminada de reserva. Un modelo principal propio de un agente también es estricto si no tiene sus alternativas expresamente configuradas. Véase la política de selección y reserva.

Si quieres utilizar el predeterminado y su política preparada, consulta /model status y usa /model default en esa conversación. Después vuelve a comprobar el estado: una preferencia de cuenta compatible puede mantenerse. Si prefieres elegir otra referencia explícitamente, selecciona una del catálogo que tengas preparada y acepta que esa nueva selección también será estricta. La guía de configuración de modelos explica cómo conectar y comprobar una alternativa antes de necesitarla.

Una alternativa útil debe tener acceso vigente, capacidad disponible, contexto y herramientas adecuados para el paso pendiente. Una segunda clave que comparte el mismo límite no multiplica la capacidad. Tampoco conviene llevar una conversación larga a un modelo cuya ventana efectiva sea menor sin comprobar la entrada.

La reserva puede utilizarse por frecuencia, agotamiento de perfiles, autenticación, facturación o un modelo no encontrado cuando las reglas de esa ejecución lo permiten. Los errores de formato suelen ser terminales; un desbordamiento de contexto sigue su propia recuperación. No uses una lista de modelos para ocultar un motivo que todavía no has identificado.

El plazo máximo de espera y la reserva tienen funciones distintas

El ajuste de sesión guardado retry.provider.maxRetryDelayMs, con valor predeterminado de 60 segundos, limita cuánto puede retener el turno una espera solicitada por el servidor cuando hay una reserva configurada. Si el mínimo del servidor supera ese tope, OpenClaw puede pasar directamente a una alternativa apta. Sin reserva, respeta el mínimo completo; el valor 0 desactiva ese tope. No significa que una cuota se renueve en 60 segundos. Son las condiciones de la política de recuperación actual.

Hay otro límite separado para las esperas internas de SDK que integra OpenClaw, controlado por OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS. Su finalidad es devolver el control al mecanismo de recuperación. No copies ambos ajustes como si fueran un único tiempo máximo del proveedor ni supongas que describen un SDK ejecutado fuera de OpenClaw.

Si una alternativa responde, comprueba qué modelo y cuenta la atendieron. La reserva se aplica al turno: no reemplaza permanentemente el modelo seleccionado de la conversación. El próximo turno puede volver a empezar por el principal, por lo que conviene mantener la carga reducida.

El 429 de contexto largo necesita acceso adecuado

Si el mensaje exacto es Extra usage is required for long context requests y solo fallan sesiones largas, revisa la selección de contexto y la elegibilidad de la credencial. No lo trates automáticamente como una ráfaga ni como context_length_exceeded. La sección oficial de OpenClaw sobre este error describe tres salidas:

1. Utilizar una ventana estándar. Selecciona un modelo de esa modalidad y prepara una entrada que quepa. Si necesitas reducir historial, conserva primero los resultados y sigue la recuperación de contexto y compactación.
2. Utilizar una credencial apta para solicitudes largas. Comprueba sus condiciones con el proveedor antes de elegirla; tener una clave API no demuestra por sí solo esa elegibilidad.
3. Utilizar una reserva apta ya configurada. Debe admitir la entrada y estar permitida por la selección actual, además de tener acceso disponible.

Un ajuste antiguo context1m puede requerir retirada en un modelo anterior que no sea de disponibilidad general; no borres ese campo indiscriminadamente en modelos actuales compatibles. Tampoco actives uso adicional de pago ni elimines historial como primera reacción al mensaje. La decisión es elegir una solicitud y un acceso que sean compatibles, conservando el trabajo que necesitas continuar.

Si el 429 aparece al instalar desde ClawHub

Pausa las búsquedas, instalaciones o actualizaciones repetidas y lee la información de espera de esa respuesta. ClawHub tiene límites separados para lectura, escritura y descarga; una búsqueda correcta no demuestra que la siguiente descarga tenga presupuesto disponible. Sus peticiones anónimas se limitan por IP y las autenticadas con un Bearer válido por usuario. Un token ausente o inválido vuelve al límite por IP. Así lo establece la API de ClawHub.

Si varias personas comparten la salida de red, puedes alcanzar el límite anónimo aunque tú hayas enviado pocas solicitudes. La guía de solución de problemas de ClawHub aconseja iniciar sesión cuando sea posible y reintentar tras el plazo indicado. Para la CLI independiente, los comandos documentados son:

clawhub login
clawhub whoami

whoami confirma la identidad de esa CLI; no prueba que el instalador nativo de OpenClaw utilice el mismo token. La presentación de ClawHub distingue los comandos nativos openclaw skills y openclaw plugins de la CLI independiente para operaciones del registro. Comprueba cuál falló antes de atribuirle un acceso autenticado.

Interpreta las cabeceras con sus unidades:

Estas unidades corresponden a ClawHub; no traslades el formato Unix a cabeceras de OpenAI que expresan duraciones. El límite aplicado por la respuesta concreta resulta más útil que una cifra general de la documentación.

Después del plazo, vuelve a intentar únicamente la operación pendiente. Comprueba que se instaló la versión esperada en el espacio de trabajo correcto y que no se sobrescribieron cambios locales. Si el nuevo error describe incompatibilidad, permisos o una versión retenida por revisión, detén la vía de espera y trata ese motivo. Cambiar de modelo o renovar su clave no resuelve esos errores del registro.

Recupera la tarea sin repetir lo que ya terminó

Antes de cancelar un turno o volver a enviarlo, comprueba los archivos, resultados de herramientas e identificadores de operaciones. Un modelo puede fallar al redactar la respuesta después de que una herramienta haya escrito un archivo o completado otra acción.

La recuperación documentada de OpenClaw continúa el historial existente, conserva trabajo terminado e indica al agente que revise las acciones interrumpidas antes de repetirlas. No exige reenviar toda la solicitud original. Una aprobación pendiente, una herramienta aún activa, la cancelación o el plazo final pueden impedir la continuación. Véase la política de reintentos.

Si el turno termina con error, deja una nota breve a partir de resultados que puedas comprobar tú:

Objetivo: terminar el análisis de inventario.
Completado: inventario.csv existe y su exportación está verificada.
Pendiente: calcular las diferencias y redactar la explicación.
Acciones que no deben repetirse: exportación; ningún envío autorizado.
Último rechazo: 429 del proveedor y modelo anotados en el registro.
Próximo paso: leer el archivo existente y continuar el cálculo pendiente.

Adapta los datos a tu tarea. Cuando se recupere el acceso, pide que compruebe el estado guardado y haga solo el siguiente paso. Si una operación externa quedó incierta, verifica su resultado en el servicio antes de autorizar su repetición. Cancelar no deshace un efecto ya producido.

Comprueba la recuperación con estas señales, en orden:

1. Acceso disponible: el estado ya no muestra el bloqueo relevante o existe una alternativa apta. Esto permite intentarlo; aún no prueba una respuesta.
2. Respuesta completa: una petición breve por la selección afectada termina sin 429. Es una solicitud real que puede consumir tokens; evita una batería de pruebas concurrentes.
3. Trabajo retomado: el paso pendiente produce el resultado esperado y los archivos o acciones anteriores siguen presentes, sin duplicados.
4. Carga estable: al reanudar gradualmente, el mismo límite no reaparece. Si reaparece, vuelve a pausar los productores y revisa la capacidad compartida.

Un texto parcial o una herramienta terminada no equivalen a una respuesta completa del modelo. Tampoco --check con código cero demuestra éxito de una llamada. models status --probe envía solicitudes reales y puede activar límites; no lo añadas automáticamente al diagnóstico.

Evita que varias fuentes llenen de nuevo el mismo límite

Revisa qué genera peticiones al mismo acceso: conversaciones simultáneas, tareas programadas, agentes y aplicaciones externas. Pausa o espacía las fuentes que puedas controlar y reanuda primero una tarea. Si el límite es por tokens, reduce las salidas solicitadas y el material innecesario; si es por número de solicitudes, evita fragmentar una tarea sencilla en decenas de llamadas.

No añadas un reintento infinito alrededor de OpenClaw. Los reintentos del SDK, del controlador y de un script externo pueden multiplicar los intentos efectivos. OpenAI señala que las peticiones fallidas también consumen límites por minuto. Respeta una cantidad de intentos y un plazo total acotados en cualquier automatización propia; aplaza la tarea si el tiempo mínimo del servidor supera lo que puedes esperar.

Si necesitas escalar un fallo persistente, conserva versión, hora, agente, proveedor/modelo, motivo exacto, plazo comunicado y alternativas intentadas. Comparte solo el fragmento pertinente sin claves ni contenido privado. En un seguimiento de registros pueden repetirse líneas al cambiar de fuente o reconectar: utiliza los identificadores y horas para no contar cada línea repetida como una petición nueva.

Preguntas frecuentes

¿Cuánto tiempo hay que esperar para solucionar el error 429 de OpenClaw?

Al menos el plazo válido que indique el proveedor para un límite temporal. Si se agotó una ventana diaria, semanal o mensual, espera su renovación o usa una alternativa apta; una pausa fija de uno o dos minutos no resuelve cualquier cuota. La política de OpenClaw distingue ambos casos.

¿Reiniciar o crear otra clave elimina el límite?

No garantiza capacidad nueva. OpenClaw conserva la espera del perfil en SQLite y el proveedor mantiene sus propias cuotas. En OpenAI, las claves pueden compartir los límites de la organización y del proyecto; algunos modelos también comparten capacidad. Consulta perfiles y recuperación y límites de OpenAI.

¿Por qué falla el modelo elegido aunque haya alternativas?

Porque una selección explícita puede ser estricta y no usar la reserva predeterminada. Consulta /model status; si tu intención es usar la política predeterminada preparada, vuelve a ella con /model default. La alternativa debe estar configurada, tener acceso disponible y admitir la tarea, según la política de reserva.

¿Tengo que borrar la conversación si solo falla con contexto largo?

No. El error exacto Extra usage is required for long context requests requiere comprobar la elegibilidad del acceso y la ventana seleccionada. Puedes preparar una entrada estándar, una credencial apta o una reserva compatible, conservando resultados e historial necesarios. La guía específica oficial distingue estas opciones.

¿Un 429 de ClawHub significa que agoté los tokens del modelo?

No lo demuestra. La búsqueda o descarga está sujeta a los límites del registro de ClawHub. Sigue sus cabeceras de espera y comprueba la autenticación del cliente que hace la operación; cambiar la clave del modelo no renueva esa capacidad. Véase la solución de problemas de ClawHub.