Erros e motivos

Toda resposta de envio traz um codigo_motivo estável, para o agente decidir o que fazer, e uma message, para pessoas. Os erros de acesso e de servidor vêm com error.code e retryable (se vale tentar de novo).

Envio adiado (`adiar`): tente de novo depois de `quando`

Código	Por quê
`outside_send_window`	fora do horário de envio que o dono ligou (padrão 08:00 às 21:00 no WhatsApp; 07:00 às 23:00 no Telegram; no fuso da conexão). A mensagem diz a hora: "tente de novo depois das HH:MM"
`pacing_wait`	ainda no intervalo mínimo entre envios
`burst_pause`	pausa depois de uma rajada de envios
`cap_hour_reached` / `cap_day_reached`	teto da hora ou do dia atingido
`cadence_variation`	ritmo regular demais; adiado alguns instantes
`reply_other_chat_needs_confirmation`	envio para outra conversa logo depois de ler mensagem de outra pessoa: aprove no painel e repita com o `confirmation_id`

Envio negado (`negar`): não insista igual

Código	O que fazer
`destination_not_allowed`	o destino não está na lista permitida. Inclua no painel, se fizer sentido
`session_paused`	a conexão está pausada (pelo disjuntor, por você ou pelo agente). Retome no painel
`scope_missing`	a chave não tem a permissão para essa ação
`action_disabled_by_default`	ação de risco alto, desligada por padrão
`first_contact_daily_cap`	chegou ao teto de primeiras mensagens do dia (para quem nunca falou com o número; o dono escolhe o teto em Regras de envio, até 3). Tente de novo depois do horário do campo `quando`; responder a quem já escreveu continua normal
`cold_requires_optin` / `cold_mass_denied` / `cold_cap_reached`	contato frio, só no modo local: no hospedado quem está fora da lista recebe `destination_not_allowed`
`duplicate_content_denied`	o mesmo texto já foi para muitas pessoas. Varie o texto
`too_many_links`	mais de 1 link na mensagem
`auto_reply_cap_conversation`	3 respostas seguidas sem a pessoa escrever de novo. Espere ela responder
`conversation_cap_hour` / `conversation_cap_day`	teto de respostas nessa conversa
`conversation_paused_pingpong`	vai e volta automático demais. A conversa volta quando você falar nela
`new_conversations_cap_hour` / `new_conversations_cap_day`	teto de conversas novas atendidas
`forward_denied`	reencaminhar link ou mídia de outra pessoa: aprove no painel e repita com o `confirmation_id`
`queue_horizon_exceeded`	só poderia sair daqui a mais de 48 horas
`idempotent_replay`	esse mesmo pedido já foi decidido; nada foi reenviado. Para repetir de propósito, mande outra `idempotency_key`
`idempotency_conflict`	a mesma `idempotency_key` foi usada com outro texto

Envio que falhou

Código	O que fazer
`send_failed`	o envio falhou e nada foi entregue. Pode tentar de novo
`send_uncertain`	não sabemos se saiu (o WhatsApp não respondeu a tempo). Confira no chat antes de reenviar; para reenviar mesmo assim, use outra `idempotency_key`
`wa_not_connected` / `telegram_not_connected`	a conexão não está de pé. Veja o status e, se preciso, pareie de novo no painel

Histórico, mídia e áudio (ainda não disponíveis)

Código	O que significa
`history_disabled`	a importação de histórico está desligada. Ainda não dá para ligar pelo painel
`media_disabled`	a busca de mídia recebida está desligada. Ainda não dá para ligar pelo painel

Editar e apagar

Código	O que fazer
`message_not_found`	não achamos essa mensagem nessa conversa
`not_your_message`	só dá para editar ou apagar mensagem que o Felku enviou nessa conversa
`key_bound_to_other_channel`	a chave está presa à outra conexão (WhatsApp ou Telegram). Use uma chave da conexão certa
`edit_window_closed`	o WhatsApp só deixa editar até ~15 minutos depois do envio
`delete_window_closed`	o WhatsApp só deixa apagar para todos até ~2 dias depois do envio

Acesso

HTTP	Código	O que fazer
401	`unauthorized`	chave ausente, errada, vencida ou revogada. Confira o cabeçalho `Authorization: Bearer ...`
403	`connection_required`	a chave é válida, mas a conta ainda não conectou o WhatsApp nem o Telegram. Conecte um canal no painel
403	`not_your_connection`	a chave não pode usar essa conexão (é de outra conta)
405	`method_not_allowed`	use `POST`

Protocolo MCP

Código	O que significa
`-32602` "Unknown tool"	a ferramenta não existe ou a chave não tem a permissão dela
`-32602` "Invalid arguments"	argumento faltando, a mais ou fora do tamanho
`-32020` "Header mismatch"	na revisão `2026-07-28`, os cabeçalhos `MCP-Protocol-Version`, `Mcp-Method` ou `Mcp-Name` não batem com o corpo
`-32022` "Unsupported protocol version"	versão do MCP que o servidor não conhece; a resposta lista as aceitas

Avisos de conexão

Código	O que fazer
`linked_devices_others` / `linked_devices_unofficial`	o número tem outros aparelhos vinculados. No celular, em Dispositivos conectados, remova os que não usa: aparelhos demais derrubam a conexão

Erros comuns

"O agente não vê as ferramentas." Confira a URL, o cabeçalho Authorization e se a chave não foi revogada. Se a resposta for connection_required, conecte um canal no painel. Peça "liste as ferramentas do felku-connect". Se aparecerem só algumas, a chave tem poucas permissões.
"O agente lê as mesmas mensagens toda vez." Ele não está mandando o next_cursor anterior em after.
"A mensagem não saiu e não deu erro." Veja o acao: adiar quer dizer "ainda não"; o servidor não envia sozinho depois.
"Fora do horário" à noite. O horário de envio vale no fuso da conexão; a mensagem diz qual é.
"Dois agentes responderam a mesma mensagem." Cada chave lê pelo próprio cursor. Deixe só um agente com permissão de envio por conexão.
"A conexão caiu." O WhatsApp derruba aparelhos vinculados de vez em quando. Veja o estado com felku_get_connection_status ou no painel e pareie de novo em Conexões.

Lista completa de códigos

Todos os códigos que o servidor pode devolver, com o texto que acompanha cada um. A lista é gerada do código do servidor; alguns são raros ou internos.

Códigos de acesso, conta e servidor (`error.code`)

Código	Texto
`unauthorized`	Chave ausente ou inválida.
`forbidden_origin`	Origem não permitida.
`forbidden_host`	Host não permitido.
`bad_request`	Pedido malformado.
`not_found`	Não encontrado.
`method_not_allowed`	Método HTTP não permitido aqui.
`payload_too_large`	Corpo grande demais.
`risk_not_accepted`	É preciso aceitar o aviso de risco antes de conectar.
`risk_version_outdated`	O aviso de risco mudou. Leia a versão atual e aceite de novo antes de conectar.
`allowlist_missing`	Nenhum número está liberado para o agente conversar. Adicione os números com quem ele pode falar (no painel; no modo local, em FELKU_CONNECT_WA_ALLOW_NUMBERS). Enquanto isso, nada é lido nem enviado.
`invalid_number`	Número ou identificador inválido. Use o telefone com DDI (ex.: +55 11 91234-5678).
`allowlist_limit`	Você chegou ao limite de números do seu plano. Remova um para adicionar outro.
`trial_one_chat`	No teste grátis o agente conversa com 1 chat do Telegram. Remova o atual para adicionar outro, ou assine.
`trial_contacts_limit`	No teste grátis o agente conversa com você e mais <limite> contatos. Remova um para adicionar outro, ou assine para liberar mais.
`state_unreadable`	estado de segurança ilegível depois de reiniciar; confira a atividade e retome no painel, em Conexões
`trial_person_only`	No teste grátis o agente só conversa com uma pessoa (chat privado do Telegram). Grupos e canais do Telegram não são aceitos em nenhum plano.
`already_in_list`	Esse número já está na lista.
`allowlist_entry_not_found`	Esse item não está na sua lista.
`wa_adapter_unavailable`	O adaptador de WhatsApp não está disponível neste servidor.
`wa_not_connected`	O WhatsApp não está conectado.
`telegram_not_connected`	O Telegram não está conectado. Conecte o seu bot no painel, em Conexões › Nova conexão › Telegram.
`unavailable_shared_bot`	Leitura de mensagens indisponível: este bot é compartilhado com a produção do Felku e o recebimento está desligado de propósito.
`invalid_token`	Token do bot inválido.
`telegram_unreachable`	Não consegui falar com o Telegram agora.
`webhook_conflict`	Este bot tem um webhook ativo; receber por polling entraria em conflito. O recebimento foi parado e nada foi apagado.
`unknown_tool`	Ferramenta desconhecida.
`bad_arguments`	Argumentos inválidos para esta ferramenta.
`send_failed`	O envio falhou. Nada foi entregue.
`send_uncertain`	Não sabemos se a mensagem saiu (tempo esgotado). Confira no chat antes de reenviar; para reenviar mesmo assim, use outra idempotency_key.
`message_not_found`	Não achei essa mensagem na caixa de entrada deste chat (ou ela já passou do prazo de guarda).
`not_your_message`	Só dá para editar ou apagar mensagens que o Felku enviou para este chat.
`edit_window_closed`	Esta mensagem não pode mais ser editada: no <canal>, a edição vale até <janela> depois do envio.
`delete_window_closed`	Esta mensagem não pode mais ser apagada para todos: no <canal>, isso vale até <janela> depois do envio.
`history_disabled`	O histórico importado está desligado para esta conexão.
`history_notice_required`	Para ligar o histórico é preciso aceitar o aviso.
`history_notice_outdated`	O aviso do histórico mudou: leia a versão atual e aceite de novo.
`history_chat_not_allowed`	Só dá para ler o histórico de conversas que estão na lista de permitidos.
`history_no_anchor`	Ainda não há histórico deste chat para usar como ponto de partida.
`media_disabled`	O recebimento de mídia está desligado para esta conexão.
`media_too_large`	Essa mídia é grande demais para ser entregue.
`media_expired`	A mídia já expirou: ela só fica disponível por alguns minutos depois de chegar.
`media_unsupported`	Este tipo de mídia não pode ser baixado (só imagem, documento, vídeo, áudio e figurinha).
`media_unavailable`	Não foi possível obter essa mídia.
`notice_required`	Para ligar isto é preciso aceitar o aviso.
`notice_outdated`	O aviso mudou: leia a versão atual e aceite de novo.
`transcription_unavailable`	A transcrição de áudio não está configurada neste servidor.
`transcription_not_in_plan`	O seu plano não inclui transcrição de áudio.
`rate_limited`	Muitas chamadas. Tente de novo em instantes.
`internal_error`	Erro interno.
`header_mismatch`	Os cabeçalhos HTTP não batem com o corpo do pedido.
`unsupported_protocol_version`	Versão do protocolo MCP não suportada.
`invalid_credentials`	E-mail ou senha incorretos.
`too_many_attempts`	Muitas tentativas. Aguarde um pouco e tente de novo.
`weak_password`	A senha precisa ter entre 10 e 128 caracteres.
`invalid_email`	Esse e-mail não parece válido.
`terms_not_accepted`	É preciso aceitar os Termos e a Política de Privacidade.
`terms_version_outdated`	Os Termos mudaram. Recarregue a página para ver a versão atual e aceite de novo.
`invalid_or_expired_token`	Este link é inválido ou expirou. Peça um novo.
`invalid_or_expired_code`	Código inválido ou expirado. Peça um novo.
`check_email`	Se o e-mail puder ser usado, enviamos um código para ele.
`session_required`	Entre na sua conta para continuar.
`email_not_verified`	Confirme o seu e-mail para continuar.
`checkout_in_progress`	Já existe um pagamento em andamento. Conclua-o ou aguarde um minuto para tentar de novo.
`withdrawal_window_closed`	O prazo de <days> dias para desistir da compra já passou.
`plan_required`	Escolha um plano para continuar.
`billing_state_blocks_action`	O estado da sua assinatura não permite esta ação.
`delete_confirmation_required`	Confirme a exclusão digitando a palavra pedida e a senha.
`not_your_connection`	Esta conexão pertence a outra conta.
`connection_required`	Sua chave é válida, mas nenhum canal está conectado ainda. Conecte o WhatsApp ou o Telegram no painel (Conexões › Nova conexão) antes de usar a chave.
`key_bound_to_other_channel`	Esta chave está presa a outra conexão (WhatsApp ou Telegram) e não pode usar as ferramentas deste canal.
`key_not_found`	Chave não encontrada.
`accounts_disabled`	As contas não estão ligadas neste servidor.
`service_busy`	Servidor ocupado. Tente de novo em instantes.
`downgrade_requires_choice`	Escolha quais números continuam antes de descer de plano.
`same_plan`	Este já é o seu plano.

Motivos do envio (`codigo_motivo`)

Código	Texto
`ok`	Pode enviar.
`invalid_request`	Pedido inválido: campo <campo>.
`kill_switch_session`	Esta conexão foi desligada pelo interruptor de emergência.
`kill_switch_key`	Esta chave foi desligada pelo interruptor de emergência.
`profile_unknown`	O perfil de limites <perfil> não existe. Nada é enviado sem limites.
`scope_missing`	Esta chave não tem o escopo <escopo>.
`idempotency_key_required`	Envio real exige uma chave de idempotência (o servidor gera uma sozinho quando você não manda).
`idempotent_replay`	Este pedido já foi decidido antes. Nada será reenviado. Para repetir a mesma mensagem de propósito, mande outra idempotency_key.
`idempotency_conflict`	A mesma chave de idempotência foi usada com outro conteúdo.
`action_disabled_by_default`	A ação <acao> (risco <nivel>) vem desligada. Só um escopo específico da chave a libera.
`channel_requires_dedicated_number`	Esta ação só é permitida em um número dedicado.
`session_paused`	A conexão está pausada (<motivo>). Só uma pessoa pode retomar.
`destination_not_allowed`	Este número não está na sua lista de contatos. Para o agente falar com ele, adicione-o no painel, em Conexões, na tela do canal (Com quem o agente pode conversar).
`allowlist_wildcard_not_allowed`	Este perfil não permite liberar todos os destinos.
`cold_requires_optin`	Primeira mensagem para quem nunca escreveu exige a confirmação de que a pessoa pediu o contato.
`cold_mass_denied`	Envio para lista fria foi negado: já houve <destinos> destinos frios na janela.
`duplicate_content_denied`	Este conteúdo já foi enviado a <destinos> destinos nas últimas 24 h. O limite existe contra envio em massa.
`conversation_paused_pingpong`	Esta conversa foi pausada por trocas automáticas repetidas. O dono precisa falar para liberar.
`auto_reply_cap_conversation`	Limite de <max> respostas automáticas seguidas sem uma nova mensagem da pessoa.
`conversation_cap_hour`	Limite de <teto> respostas por hora nesta conversa.
`conversation_cap_day`	Limite de <teto> respostas por dia nesta conversa.
`new_conversations_cap_hour`	Limite de <teto> conversas novas atendidas por hora. Quem já está em conversa continua.
`new_conversations_cap_day`	Limite de <teto> conversas novas atendidas por dia. Quem já está em conversa continua.
`cadence_variation`	O ritmo dos envios estava regular demais; o envio foi adiado alguns instantes para variar.
`linked_devices_unofficial`	Este número já tem <count> aparelho(s) vinculado(s) não oficial(is). Remova os que não usa: aparelhos demais derrubam a conexão.
`linked_devices_others`	Este número tem <count> outro(s) aparelho(s) vinculado(s). Confira em Dispositivos conectados e remova os que não usa: aparelhos demais derrubam a conexão.
`reply_other_chat_needs_confirmation`	Responder a um terceiro em outro chat exige confirmação do dono.
`forward_denied`	Link ou mídia recebidos de terceiro não são reenviados para outro chat sem confirmação.
`outside_send_window`	Fora do horário de envio. Tente de novo depois das <hora> (<fuso>).
`pacing_wait`	Aguardando o intervalo mínimo entre envios.
`burst_pause`	Pausa depois de uma rajada de envios.
`cap_hour_reached`	Teto por hora atingido (<usado> de <teto>).
`cap_day_reached`	Teto diário atingido (<usado> de <teto>).
`cold_cap_reached`	Teto de primeiras mensagens atingido (<usado> de <teto>).
`first_contact_daily_cap`	Você já mandou <usado> primeiras mensagens hoje (o teto é <teto> por dia, igual em todos os planos). Volta a liberar às <volta> (<fuso>). Responder quem já escreveu continua normal.
`group_rate_limited`	Limite de <max> operações de grupo na janela. Aguarde.
`limit_zero`	Este limite está em zero neste perfil: a ação está desativada.
`queue_horizon_exceeded`	A espera passaria do limite da fila. O pedido foi negado.
`too_many_links`	Mensagem com <links> links; o máximo é <max>.
`loop_echo_discarded`	Eco de uma mensagem enviada por nós, descartado.
`owner_outbound_ignored`	Mensagem do dono para um terceiro não é entrada para o agente.
`history_not_delivered`	Histórico ou mensagem offline não é entregue ao agente.
`inbound_expired`	A mensagem é antiga demais para ser entregue ao agente.
`duplicate_inbound`	Mensagem repetida, ignorada.
`inbound_filtered`	Este tipo de entrada não é entregue ao agente (grupo, status, canal, reação, edição ou chamada).
`already_claimed`	Outro agente já assumiu a resposta a esta mensagem.
`lid_unresolved`	Não foi possível identificar o remetente (identificador LID sem correspondência).