Codigos de Erro
Lista de codigos de erro exibidos nos alertas do agente e como resolver.
Como funcionam os alertas
Quando o QuickClaw detecta um problema com seu agente, um alerta e exibido automaticamente no BotAlertBanner na tab Overview. Cada alerta possui um codigo de erro, severidade e instrucoes de resolucao.
Alertas sao gerados apos 3 erros consecutivos do mesmo tipo, evitando falsos positivos por problemas transientes. Quando o problema e resolvido, o alerta e removido automaticamente (auto-resolve).
Tabela de erros
| Recurso | Severidade | Descricao |
|---|---|---|
| auth_error | Critical | API key invalida ou expirada |
| billing_error | Critical | Creditos insuficientes |
| rate_limit | Warning | Muitas requisicoes ao provedor |
| server_error | Warning | Erro no servidor do provedor |
| timeout | Info | Requisicao expirou (timeout) |
| container_crash | Critical | Container caiu inesperadamente |
| circuit_breaker | Critical | Circuit breaker aberto |
auth_error
Critical
Descricao: A API key configurada no agente e invalida, expirou ou foi revogada pelo provedor de IA.
Resolucao:
- Flex (BYOK): Acesse o painel do provedor (Anthropic, OpenAI, Google ou OpenRouter), verifique se a chave ainda e valida. Se necessario, gere uma nova chave e atualize na tab Secrets & API Keys do QuickClaw
- Starter/Pro: O problema esta na chave da plataforma. Contate suporte@myquickclaw.com para resolucao
billing_error
Critical
Descricao: Creditos insuficientes para processar a requisicao. Tanto os creditos de assinatura quanto os avulsos estao zerados.
Resolucao:
- Faca um top-up de creditos para restaurar o saldo imediatamente
- Ou aguarde a renovacao mensal dos creditos de assinatura (data visivel na pagina de Assinatura)
rate_limit
Warning
Descricao: O agente enviou muitas requisicoes ao provedor de IA em um curto periodo de tempo e foi temporariamente limitado (HTTP 429).
Resolucao:
- Aguarde alguns minutos. O rate limit e automaticamente removido pelo provedor apos um periodo de cooldown (geralmente 1-5 minutos)
- Se ocorre com frequencia, considere reduzir o volume de mensagens simultaneas ou trocar para um modelo com limites mais altos
server_error
Warning
Descricao: O servidor do provedor de IA retornou um erro interno (HTTP 500). Isso nao e um problema no QuickClaw — e uma falha temporaria no lado do provedor.
Resolucao:
- Problema temporario. Erros de servidor do provedor se resolvem sozinhos em minutos. O QuickClaw tentara automaticamente nas proximas mensagens
- Se persistir por mais de 30 minutos, verifique a pagina de status do provedor (status.anthropic.com, status.openai.com, etc.)
timeout
Info
Descricao: A requisicao ao provedor de IA demorou mais do que o tempo limite permitido e foi cancelada.
Resolucao:
- Tente novamente. Timeouts podem ocorrer quando o modelo esta sobrecarregado, especialmente em horarios de pico
- Se o problema for recorrente, considere usar um modelo mais rapido (ex: Sonnet 4.5 ao inves de Opus 4.6) para respostas mais curtas
- Mensagens muito longas ou prompts com muito contexto tambem podem causar timeout
container_crash
Critical
Descricao: O container do agente caiu de forma inesperada. Isso pode ocorrer por estouro de memoria, bug no OpenClaw ou problema de infraestrutura.
Resolucao:
- Reinicio automatico: O QuickClaw reinicia o container automaticamente em ate 3 tentativas. Na maioria dos casos, o agente volta a funcionar sem intervencao
- Se o crash se repetir apos 3 tentativas, o agente ficara em status
error. Tente reiniciar manualmente pelo dashboard - Se o problema persistir, pode ser necessario verificar se alguma skill instalada esta causando o crash
circuit_breaker
Critical
Descricao: O agente acumulou muitas falhas consecutivas ao tentar se comunicar com o provedor de IA. O circuit breaker foi acionado para evitar mais tentativas falhas.
Resolucao:
- Aguarde 5 minutos. O circuit breaker faz reset automatico apos um periodo de espera, permitindo novas tentativas
- Enquanto o circuit breaker esta aberto, nenhuma requisicao e enviada ao provedor. Isso protege tanto o agente quanto o provedor de uma cascata de erros
- Apos o reset, o agente tenta novamente. Se o problema original foi resolvido (ex: provedor voltou a funcionar), o agente retoma normalmente
Flex vs Starter/Pro
A responsabilidade pela resolucao de erros depende do plano do seu agente:
- Flex (BYOK): Como voce usa sua propria chave de API, erros de autenticacao (
auth_error), billing e rate limit sao de sua responsabilidade. Voce gerencia a chave diretamente no painel do provedor - Starter/Pro: A chave de API e gerenciada pela plataforma. Erros de
auth_errorouserver_errorpersistentes devem ser reportados ao suporte em suporte@myquickclaw.com. A equipe QuickClaw investigara e resolverá o problema
Mensagens diferenciadas
O BotAlertBanner exibe mensagens de resolucao diferentes dependendo do seu plano. Bots Flex veem instrucoes para verificar a propria chave, enquanto agentes Starter/Pro veem instrucoes para contatar o suporte.
