Contexto
Sistemas de inteligência artificial podem falhar por indisponibilidade temporária, limite de uso, entrada extensa, fonte inacessível, permissão insuficiente, interrupção da resposta ou erro na execução de uma ferramenta.
A interface não deve reduzir todos esses casos a um aviso genérico. Ela precisa comunicar o que falhou em termos compreensíveis e oferecer um próximo passo proporcional, preservando o trabalho já feito sempre que possível.
Identifique a etapa que falhou e explique a causa quando ela for conhecida. Diferencie uma falha temporária, um limite de uso, uma entrada inválida, uma permissão insuficiente, uma indisponibilidade de fonte ou uma ação parcialmente concluída.
Ofereça pelo menos um caminho claro de recuperação no mesmo contexto. Use ações específicas, como “Tentar novamente”, “Editar pedido”, “Iniciar nova conversa”, “Reduzir arquivos” ou “Reconectar fonte”, conforme a causa.
Preserve o pedido, os arquivos e o trabalho já realizado. Em ações com efeito externo, informe se algo foi executado, se foi executado parcialmente ou se a tentativa nem começou, para evitar duplicidade ao tentar novamente.
Quando a recuperação depender de outra condição, mostre uma alternativa proporcional, como consultar o status do serviço, revisar permissões ou procurar suporte com um identificador técnico como informação secundária.
Porque isso importa?
Uma falha sem orientação cria um beco sem saída, faz a pessoa repetir tentativas sem entender o problema e pode levar à perda do trabalho ou à duplicação de uma ação externa.
Mensagens de erro úteis preservam o controle e calibram a confiança. A pessoa entende o que aconteceu, o que ainda está seguro para fazer e qual próximo passo tem maior chance de resolver o problema.
Quando usar?
- Geração de texto, imagem, áudio, código ou análise interrompida.
- Falha de ferramenta, agente, conector ou integração externa.
- Limite de uso, excesso de contexto ou capacidade temporariamente indisponível.
- Entrada inválida, arquivo extenso demais ou fonte inacessível.
- Falha de autenticação, permissão ou conexão.
- Ação executada parcialmente ou com resultado incerto.
- Bloqueio de segurança ou política quando a pessoa puder ajustar o pedido.
Quando evitar?
- Não apresente erro enquanto o sistema ainda está carregando e o estado não estiver definido.
- Não ofereça “Tentar novamente” quando a ação externa puder ser duplicada e o estado não estiver claro.
- Não use erro técnico para esconder uma recusa de segurança ou política.
- Não envie a pessoa ao suporte quando houver uma recuperação simples e conhecida.
- Não substitua uma mensagem contextual por um código como única explicação.
Recomendações
Faça
- Nomeie o que falhou.
- Explique a causa em linguagem simples quando possível.
- Ofereça uma ação de recuperação no local.
- Use verbos específicos nos controles.
- Preserve prompt, arquivos e trabalho.
- Mostre o estado de ações externas.
- Ofereça uma alternativa quando repetir não for suficiente.
- Deixe detalhes técnicos em uma camada secundária.
Evite
- Não use apenas “Algo deu errado”.
- Não deixe a pessoa em um painel vazio ou carregamento infinito.
- Não repita automaticamente uma ação externa sem esclarecer o estado.
- Não obrigue a começar de novo quando o contexto puder ser preservado.
- Não esconda a causa atrás de cor ou ícone.
- Não ofereça um botão genérico que não indique a consequência.
- Não mostre o identificador técnico como ação principal.
