Códigos de erro

HTTP

Código	Significado	Como resolver
400	Body inválido (Zod schema falhou)	Confira error.issues na resposta — mostra o campo problemático
401	JWT ausente/inválido/expirado	Refaça login. Tokens não expiram por padrão, mas podem ser revogados.
403	Sem permissão (role insuficiente)	Verifique x-workspace-id e role do usuário no workspace
404	Recurso não existe ou não pertence ao workspace	Confira IDs e workspace
409	Conflito (ex: intent com mesmo nome)	Use nome único ou faça PUT no existente
422	Validação semântica falhou	Ex: trocar status pra valor inválido
429	Rate limit	Default: 100 req/min por IP. Aguarde 60s.
500	Erro interno	Olhe logs PM2 (pm2 logs agentflow-api); se persistir reporte.

Erros conhecidos no Worker

extractFields failed: 400 prompt is too long: 200000+ tokens

Causa: histórico da conversa + training context excedeu 200k tokens (limite Claude).

Fix:

• Reduzir trainingContext (use apenas o essencial — ele é injetado em toda mensagem)
• Aumentar messageGroupingTime (debounce mais agressivo)
• Fechar conversas antigas (autoCloseMinutes mais baixo)
• Limpar mensagens antigas via UI Chat → Conversa → Apagar histórico

Skipping intent "X" — missing required field(s): Y

LLM emitiu a tag prematuramente sem coletar todos campos.

Fix:

• No intent.description, deixe explícito: "Antes de emitir a tag, pergunte ao usuário: idEntregador, cidade. Só emita quando tiver TODOS."
• Reduza requiredFields ao mínimo (campos opcionais não devem estar aqui)

Technical error on "X" (HTTP 0), escalating

Webhook do n8n não respondeu (timeout ou connection refused).

Fix:

• Confira se o workflow do n8n está ativo (URL pública correta)
• Whitelist 72.60.14.189 no n8n
• Use webhookMethod: GET se o endpoint só aceita GET
• Aumente timeout via env INTENT_WEBHOOK_TIMEOUT_MS

[WhatsApp:Meta] Failed to get media URL: 400

Token de mídia da Meta expirou ou app foi desconectado.

Fix:

• Reconecte o canal Meta no painel (gera novo accessToken)
• Confira se o app no Meta Developer Console tem permissão whatsapp_business_messaging

Limites

Recurso	Limite
Mensagens por agente	sem limite global; controlável via maxDailyMessages por contato
Tamanho do prompt	200k tokens (limite Claude Sonnet 4.6)
Webhook timeout	30s default (configurável)
Anexos no chat	25 MB (Meta), 16 MB (Z-API)
Approvals pendentes	sem limite, mas expiram em 24h
Conversas históricas	sem limite (cuidado com tamanho do DB)

Suporte

• Logs do servidor: pm2 logs agentflow-api --lines 200
• Logs do worker: pm2 logs agentflow-api | grep "[Worker]"
• Status do banco: docker exec agentflow-db pg_isready
• Status Redis: docker exec agentflow-redis redis-cli ping