OpenCode Free Limit Reached: cuándo esperar y cómo continuar

Cuando OpenCode muestra Free limit reached o HTTP 429, no des por hecho que todos los modelos gratuitos se restablecen a una hora fija cada día. Conserva el error original, confirma el provider y el model activos y utiliza únicamente un aviso de reset que aparezca realmente en la respuesta o en tu cuenta.

Si no existe una hora fiable, puedes esperar, elegir otro modelo que esté disponible ahora en /models o cambiar de forma explícita a un provider con facturación independiente. Antes de reanudar una tarea larga, envía una petición pequeña que no modifique archivos y comprueba la respuesta, el provider/model seleccionado y el uso registrado por el provider.

Elige la rama según el síntoma

Lo que ves	Rama probable	Primera acción
Free limit reached o FreeUsageLimitError sin cuenta atrás	Límite de la capa gratuita	No inventes un ciclo; anota la hora y espera o revisa los modelos actuales en /models
Go limit reached con una cuenta atrás real	Ventana de uso de pago de OpenCode Go	Sigue la hora que muestra esa cuenta y no la apliques a los modelos gratuitos
429, Too Many Requests o Provider is overloaded genérico	Rate limit, falta de capacidad o fallo temporal del provider	Guarda la respuesta completa, confirma provider/model, reintenta más tarde y consulta su estado
401, 404 o Model not available	Problema de autenticación, Base URL o Model ID	No esperes un reset; corrige credenciales, endpoint o configuración del modelo

El mismo código HTTP puede tener causas distintas. Un 429 puede ser una cuota gratuita agotada, un límite normal del provider o una sobrecarga temporal. Por sí solo no justifica comprar un plan ni rehacer toda la configuración.

Guarda cuatro datos antes de cambiar nada

1. El texto completo del error, no solo “429”.
2. El provider y el model seleccionados, preferiblemente como providerId/modelId.
3. El response body, tipo de error, headers y retry-after visibles, si el cliente realmente los muestra.
4. La hora del fallo y la zona horaria, el directorio del proyecto y si usabas Zen gratuito, Go o un custom provider.

Siguiendo la documentación de OpenCode Zen, ejecuta /models en la TUI para comprobar la entrada seleccionada y los modelos que aparecen ahora. También puedes ejecutar opencode models en una terminal. No uses una captura o una guía antigua para asumir que un modelo gratuito sigue disponible: la lista puede cambiar.

Comprueba además la precedencia de configuración. La documentación de configuración de OpenCode explica que OpenCode combina varias fuentes y un opencode.json del proyecto puede sobrescribir la configuración global. Haber elegido el modelo A globalmente no demuestra que el repositorio actual lo esté usando. Confía en el proyecto actual, la selección de /models y la configuración resuelta.

Confía solo en un reset que exista de verdad

Si el error actual no incluye una cuenta atrás fiable ni una hora absoluta, no deduzcas “unas horas”, “mañana” o “la semana que viene”.

En el snapshot de retry.ts de la rama dev de OpenCode abierto y revisado el 2026-10-10, FreeUsageLimitError entra en una rama estática de aviso del límite gratuito. GoUsageLimitError, en cambio, lee el header retry-after y genera una cuenta atrás. Se trata de una revisión de código fuente, no de una prueba en ejecución de tu versión instalada ni de tu cuenta.

Las solicitudes públicas #53252 y #52894 han incluido horas de ejemplo, pero son ilustraciones de la mejora solicitada, no calendarios observados de la capa gratuita. Que un issue esté cerrado tampoco demuestra que el cambio haya llegado a la versión que utilizas.

La documentación de OpenCode Go, abierta el 2026-10-10, define por separado ventanas de 5 horas, semanales y mensuales para el uso de pago. Esas reglas no permiten inferir el reset de los modelos gratuitos.

Aplica esta regla:

• Aparece una cuenta atrás o una hora exacta: guarda el texto, la zona horaria y el provider y haz un único reintento cerca de esa hora.
• No aparece una hora: considera el reset desconocido, evita reintentos rápidos y no sustituyas el dato por la ventana de otro plan.
• Solo aparece un 429 genérico: investiga throttling o sobrecarga del provider hasta que la evidencia identifique un límite gratuito.

Opción 1: esperar si necesitas el mismo modelo gratuito

Esperar es la opción más sencilla cuando la tarea no es urgente, no quieres consumo de otra API y el error apunta claramente a la capa gratuita.

1. Anota la hora del último fallo y el error sin recortar.
2. Detén los reintentos continuos para no mezclar una cuota con un rate limit transitorio.
3. Si hay un temporizador fiable, prueba cerca de la hora indicada. Si no lo hay, revisa más tarde con un intervalo aceptable para ti, sin prometer un ciclo fijo.
4. Prueba primero una petición corta, no una tarea que lea o modifique muchos archivos.

El éxito no es que OpenCode se abra ni que el proceso termine con exit code 0. El modelo elegido debe devolver contenido real y no repetir de inmediato el error original.

Opción 2: elegir otro modelo disponible ahora en /models

Si necesitas seguir trabajando pero no necesitas el modelo original, elige otra entrada que tu cuenta vea ahora y que sea accesible mediante el provider previsto.

Antes de cambiar, verifica que:

• el modelo figura en la lista actual y no solo en un tutorial antiguo;
• la entrada pertenece al provider esperado, para que cambiar de modelo no cambie silenciosamente de cuenta o facturación;
• el modelo sirve para la tarea: prueba primero una petición pequeña de comprensión de código o tool use antes de permitir cambios en el repositorio.

Cambiar de modelo no garantiza el resultado. Otro modelo gratuito puede tener su propio límite, restricciones regionales, una retirada temporal o problemas de capacidad. La recomendación correcta es “elige un modelo disponible ahora y verifícalo”, no “cambiar de modelo gratuito siempre funciona”.

Opción 3: usar explícitamente un provider con facturación independiente

Esta opción encaja cuando hay una fecha límite, aceptas un consumo de API separado y quieres que las siguientes peticiones dejen de depender de la cuota gratuita de Zen. No restablece la cuota: dirige las llamadas a otra cuenta, otra API Key y otro registro de uso.

La documentación de providers de OpenCode admite custom OpenAI-compatible providers. El flujo mínimo es:

1. Ejecuta /connect, elige Other, introduce un provider ID único y guarda la API Key en el campo de credencial.
2. Configura el mismo provider ID, el Base URL correcto y el Model ID real en opencode.json, y guarda el archivo.
3. Cierra por completo OpenCode y vuelve a iniciarlo en el mismo proyecto antes de comprobar la nueva configuración; no presupongas que una TUI ya abierta recarga en caliente un provider nuevo. Si necesitas conservar el contexto anterior, anota el directorio del proyecto y la tarea o sesión a la que debes volver, y tras reiniciar regresa de forma segura mediante el flujo disponible en tu entorno.
4. Después del reinicio, ejecuta /models, comprueba que aparece la nueva entrada y selecciona el providerId/modelId exacto, no solo su nombre visible.
5. Envía una petición pequeña que indique expresamente que no debe modificar archivos y confirma que recibes una respuesta nueva y real del modelo.
6. Revisa el registro de solicitudes, el uso o el saldo del provider de destino para comprobar que procesó esa petición. Si no existe un registro correspondiente, no afirmes que el cambio quedó verificado.

BetterToken es una opción para esta ruta independiente. Su documentación de configuración con OpenCode, abierta el 2026-10-10, indica el Base URL https://www.bettertoken.ai/v1 y una referencia como bettertoken/YOUR_MODEL_ID. No añadas /chat/completions al Base URL y asegúrate de que el campo superior model coincida exactamente con el ID real declarado en models.

El límite es importante: BetterToken no proporciona la cuota gratuita de Zen ni restablece un límite de OpenCode/Zen. Tampoco garantiza que nunca aparezca un 429 ni es automáticamente más barato sin comparar el mismo uso. Es una ruta de API separada y explícita, no un reset.

Verifica la recuperación con una petición pequeña

Utiliza la misma prueba después de esperar, cambiar de modelo o cambiar de provider:

1. Confirma otra vez el provider/model seleccionado en la interfaz.
2. Pide únicamente la palabra READY e indica que no debe modificar archivos.
3. Guarda la respuesta y la hora. Comprueba que sea una respuesta nueva del modelo, no solo una confirmación de configuración ni una salida en caché.
4. Con un provider independiente, busca el pequeño cambio correspondiente en su registro de uso, solicitudes o saldo. Si no expone esa evidencia, no afirmes que la facturación quedó verificada.
5. Si el error original no vuelve, regresa a la tarea real y ejecuta primero su paso útil más pequeño.

Un PASS válido combina una respuesta real, el provider/model esperado y evidencia de uso del lado del provider. Que el config se analice, que el cliente arranque o que exista un exit code limpio no basta por separado.

Si la petición pequeña sigue fallando

Sigue la nueva rama de error en lugar de repetir todas las correcciones:

• Vuelve Free limit reached: quizá la cuota aún no se recuperó o la selección no cambió realmente. Revisa /models y el config del proyecto.
• Aparece 401: comprueba que exista la credencial para ese provider. Ejecuta opencode auth list y repite /connect si hace falta.
• Aparece 404 o Model not available: revisa Base URL, Model ID y providerId/modelId, y ejecuta opencode models para ver el acceso actual.
• Aparece un 429 genérico o sobrecarga: trátalo como throttling del provider, reduce la frecuencia de reintento y revisa su estado; no lo sigas atribuyendo a la cuota Zen.
• El error está incompleto: usa la guía de resolución de problemas de OpenCode para consultar logs y comunica la hora, provider, model, estado y response body anonimizado.

No pegues una API Key en un issue, una captura ni un chat. Conserva los datos útiles, pero elimina Authorization headers, tokens y cualquier credencial.

Preguntas frecuentes

¿La cuota gratuita de OpenCode se restablece cada día a una hora fija?

No hay una fuente primaria fiable que demuestre que todos los modelos gratuitos compartan un único ciclo diario, semanal o mensual. Usa la hora que muestre la petición actual; si no aparece, considérala desconocida.

¿Todo 429 significa que se agotó la cuota gratuita?

No. También puede ser un rate limit normal, un límite de concurrencia o sobrecarga del provider. Interprétalo junto con provider, model, response body y tipo de error.

¿Suscribirse a OpenCode Go es la única forma de continuar?

No. Puedes esperar, elegir otro modelo disponible ahora o usar explícitamente un provider independiente. Go es un plan de pago separado y sus ventanas no prueban el reset de la capa gratuita.

¿Cambiar a BetterToken borra el límite gratuito?

No. Es una ruta independiente con su propia API Key, Base URL, Model ID y contabilidad de uso. No cambia el estado de la cuota gratuita de Zen.

Regla práctica

No resuelvas Free limit reached adivinando el ciclo de reset. Identifica el provider/model, confía solo en una hora real y elige la ruta menos disruptiva según el plazo: esperar, seleccionar un modelo disponible ahora en /models o usar un provider con facturación independiente. Antes de volver a la tarea original, demuestra la recuperación con una respuesta corta y el uso del provider.