OpenCode Free Limit Reached: esperar, trocar ou continuar

Quando o OpenCode mostra Free limit reached ou HTTP 429, não presuma que todos os modelos gratuitos reiniciam em um horário fixo todos os dias. Preserve o erro original, confirme o provider e o model ativos e use somente um aviso de reset que realmente apareça na resposta atual ou na conta.

Se não houver um horário confiável, você pode esperar, selecionar outro modelo disponível agora em /models ou mudar explicitamente para um provider com cobrança independente. Antes de retomar uma tarefa longa, envie uma solicitação pequena que não altere arquivos e confirme a resposta, o provider/model selecionado e o uso registrado pelo provider.

Escolha a ramificação pelo sintoma

O que aparece	Causa provável	Primeira ação
Free limit reached ou FreeUsageLimitError, sem contagem regressiva	Limite da faixa gratuita	Não invente um ciclo; anote o horário e espere ou veja os modelos atuais em /models
Go limit reached com contagem regressiva real	Janela de uso pago do OpenCode Go	Siga o horário exibido nessa conta; não o aplique a modelos gratuitos
429, Too Many Requests ou Provider is overloaded genérico	Rate limit, capacidade ou falha temporária do provider	Guarde a resposta completa, confirme provider/model, tente depois e consulte o status do provider
401, 404 ou Model not available	Autenticação, Base URL ou Model ID incorretos	Não espere reset; corrija credencial, endpoint ou configuração do modelo

O mesmo status HTTP pode ter causas diferentes. Um 429 pode representar cota gratuita esgotada, limite comum do provider ou sobrecarga temporária. O código sozinho não é motivo para assinar um plano nem refazer toda a configuração.

Salve quatro informações antes de mudar

1. O texto completo do erro, não apenas “429”.
2. O provider e o model selecionados, de preferência como providerId/modelId.
3. O response body, tipo de erro, headers e retry-after visíveis, se o cliente realmente os mostrar.
4. O horário da falha e o fuso, o diretório do projeto e se você usava Zen gratuito, Go ou custom provider.

Conforme a documentação do OpenCode Zen, execute /models na TUI para confirmar a entrada selecionada e os modelos listados agora. No terminal, também é possível executar opencode models. Não use captura de tela ou tutorial antigo para concluir que um modelo gratuito continua disponível; a lista pode mudar.

Verifique ainda a precedência de configuração. A documentação de configuração do OpenCode explica que o OpenCode combina várias fontes e um opencode.json do projeto pode sobrescrever a configuração global. Ter escolhido o modelo A globalmente não prova que o repositório atual o utiliza. Confie no projeto atual, na seleção de /models e na configuração resolvida.

Confie apenas em um reset que realmente exista

Se o erro atual não incluir uma contagem regressiva confiável nem um horário absoluto, não deduza “daqui a algumas horas”, “amanhã” ou “na próxima semana”.

No snapshot de retry.ts da branch dev do OpenCode aberto e verificado em 2026-10-10, FreeUsageLimitError entra em uma ramificação estática de aviso do limite gratuito. Já GoUsageLimitError lê o header retry-after e monta uma contagem regressiva. Essa é uma verificação de código-fonte, não um teste em execução da sua versão instalada ou da sua conta.

As feature requests #53252 e #52894 incluíram horários de exemplo, mas esses números ilustram o comportamento desejado; não são ciclos observados da camada gratuita. Um issue fechado também não comprova que a alteração chegou à versão do seu cliente.

A documentação do OpenCode Go, aberta em 2026-10-10, define separadamente janelas de 5 horas, semanais e mensais para o uso pago. Essas regras do Go não podem ser projetadas sobre o reset de modelos gratuitos.

Use esta regra:

• Há contagem regressiva ou horário exato: salve o texto, o fuso e o provider e faça uma única nova tentativa perto desse horário.
• Não há horário: trate o reset como desconhecido, evite repetição rápida e não substitua pelo intervalo de outro plano.
• Há somente um 429 genérico: investigue throttling ou sobrecarga do provider até a evidência apontar para a faixa gratuita.

Opção 1: esperar quando você precisa do mesmo modelo gratuito

Esperar é a escolha mais simples quando a tarefa não é urgente, você não quer consumo em outra API e o erro aponta claramente para a cota gratuita.

1. Registre o horário da última falha e o erro bruto.
2. Pare as tentativas contínuas para não misturar cota com rate limit transitório.
3. Se houver timer confiável, tente perto do horário indicado. Sem timer, verifique em um intervalo aceitável para você, sem prometer ciclo fixo.
4. Faça primeiro uma solicitação curta, não uma tarefa que leia ou altere muitos arquivos.

Sucesso não é apenas o OpenCode abrir nem o processo terminar com exit code 0. O modelo escolhido precisa retornar conteúdo real sem repetir imediatamente o erro original.

Opção 2: selecionar outro modelo disponível agora em /models

Se você precisa continuar, mas não depende do modelo original, escolha outra entrada visível agora para sua conta e acessível pelo provider esperado.

Antes da troca, confira se:

• o modelo está na lista atual, e não apenas em um guia antigo;
• a entrada pertence ao provider esperado, para a troca de modelo não virar silenciosamente uma troca de conta ou cobrança;
• o modelo serve para a tarefa: faça primeiro uma pequena solicitação de compreensão de código ou tool use antes de permitir alterações no repositório.

Trocar o modelo não garante a recuperação. Outro modelo gratuito pode ter limite próprio, restrição regional, remoção temporária ou falta de capacidade. A orientação correta é “selecione um modelo disponível agora e valide”, não “qualquer troca de modelo gratuito funciona”.

Opção 3: usar explicitamente um provider com cobrança independente

Use esta rota quando houver prazo, você aceitar consumo separado de API e quiser que as próximas solicitações deixem de depender da cota gratuita do Zen. Isso não reinicia a cota; as chamadas passam por outra conta, outra API Key e outro registro de uso.

A documentação de providers do OpenCode confirma custom OpenAI-compatible providers. O fluxo mínimo é:

1. Execute /connect, escolha Other, informe um provider ID único e salve a API Key no campo de credencial.
2. Configure o mesmo provider ID, o Base URL correto e o Model ID real em opencode.json e salve o arquivo.
3. Feche completamente o OpenCode e reinicie-o no mesmo projeto antes de verificar a nova configuração; não presuma que uma TUI já aberta fará hot reload de um provider recém-adicionado. Se você precisa preservar o contexto anterior, anote o diretório do projeto e a tarefa ou sessão à qual deve voltar e, após reiniciar, retorne com segurança pelo fluxo disponível no seu ambiente.
4. Depois da reinicialização, execute /models, confirme que a nova entrada aparece e selecione o providerId/modelId exato, não apenas o nome exibido.
5. Envie uma solicitação pequena que proíba explicitamente alterações em arquivos e confirme que recebeu uma resposta nova e real do modelo.
6. Consulte o registro de requests, o uso ou a alteração de saldo do provider de destino para confirmar que ele processou essa solicitação. Sem um registro correspondente, não afirme que a troca foi verificada.

BetterToken é uma opção para essa rota independente. A documentação de configuração no OpenCode, aberta em 2026-10-10, informa o Base URL https://www.bettertoken.ai/v1 e uma referência como bettertoken/YOUR_MODEL_ID. Não acrescente /chat/completions ao Base URL e garanta que o campo superior model seja exatamente igual ao ID real declarado em models.

O limite é importante: BetterToken não fornece a cota gratuita do Zen nem reinicia um limite do OpenCode/Zen. Também não garante ausência de todo 429 nem é automaticamente mais barato sem comparar o mesmo uso. É uma rota de API separada e explícita, não um reset.

Valide a recuperação com uma solicitação pequena

Use o mesmo teste depois de esperar, trocar de modelo ou trocar de provider:

1. Confirme novamente o provider/model selecionado na interface.
2. Peça somente a palavra READY e diga explicitamente para não alterar arquivos.
3. Salve a resposta e o horário. Verifique que é uma resposta nova do modelo, não apenas confirmação de configuração nem saída em cache.
4. Em um provider independente, procure a pequena alteração correspondente no histórico de uso, requests ou saldo. Se ele não oferecer essa evidência, não afirme que a cobrança foi verificada.
5. Confirme que o erro original não voltou, retorne à tarefa real e execute primeiro o menor passo útil dela.

Um PASS válido reúne resposta real, o provider/model esperado e evidência de uso do lado do provider. Config analisado, cliente iniciado ou exit code limpo não bastam isoladamente.

Se a solicitação pequena ainda falhar

Siga a nova ramificação em vez de repetir todas as correções:

• O mesmo Free limit reached: a cota talvez ainda não tenha voltado ou a seleção não mudou de fato. Revise /models e o config do projeto.
• Surge 401: confira se a credencial existe para esse provider. Execute opencode auth list e repita /connect se necessário.
• Surge 404 ou Model not available: revise Base URL, Model ID e providerId/modelId; depois execute opencode models para ver o acesso atual.
• Surge 429 genérico ou sobrecarga: trate como throttling do provider, reduza a frequência de tentativas e consulte o status, em vez de continuar atribuindo ao Zen.
• O erro está incompleto: use o guia de troubleshooting do OpenCode para examinar logs e informe horário, provider, model, status e response body sem segredos.

Nunca cole uma API Key em issue, captura ou chat. Preserve os dados úteis do erro, mas remova Authorization headers, tokens e outras credenciais.

Perguntas frequentes

A cota gratuita do OpenCode reinicia todo dia em horário fixo?

Não há base primária confiável para afirmar que todos os modelos gratuitos compartilham um único ciclo diário, semanal ou mensal. Use o horário exibido pela solicitação atual; se não houver, trate como desconhecido.

Todo 429 significa que a cota gratuita acabou?

Não. Ele também pode ser rate limit comum, limite de concorrência ou sobrecarga do provider. Analise junto com provider, model, response body e tipo de erro.

Assinar OpenCode Go é a única forma de continuar?

Não. Você pode esperar, escolher outro modelo disponível agora ou usar um provider independente. Go é um plano pago separado, e suas janelas não comprovam o reset da faixa gratuita.

Mudar para BetterToken limpa o limite gratuito?

Não. É uma rota independente com API Key, Base URL, Model ID e contabilização próprios. Ela não muda o estado da cota gratuita do Zen.

Regra prática

Não resolva Free limit reached adivinhando o ciclo de reset. Identifique o provider/model, confie somente em horário real e escolha a rota menos disruptiva para o prazo: esperar, selecionar um modelo disponível em /models ou usar um provider com cobrança independente. Antes de voltar à tarefa original, comprove a recuperação com uma resposta curta e o uso do provider.