Errores y motivos

Toda respuesta de envío trae un codigo_motivo estable, para que el agente decida qué hacer, y un message, para personas. Los errores de acceso y de servidor vienen con error.code y retryable (si vale la pena intentarlo de nuevo).

Envío aplazado (`adiar`): inténtalo de nuevo después de `quando`

Código	Por qué
`outside_send_window`	fuera del horario de envío que activó el dueño (predeterminado 08:00 a 21:00 en WhatsApp; 07:00 a 23:00 en Telegram; en la zona horaria de la conexión). El mensaje dice la hora: "inténtalo de nuevo después de las HH:MM"
`pacing_wait`	todavía en el intervalo mínimo entre envíos
`burst_pause`	pausa después de una ráfaga de envíos
`cap_hour_reached` / `cap_day_reached`	se alcanzó el tope de la hora o del día
`cadence_variation`	ritmo demasiado regular; aplazado unos instantes
`reply_other_chat_needs_confirmation`	envío a otro chat justo después de leer un mensaje de otra persona: aprueba en el panel y repite con el `confirmation_id`

Envío negado (`negar`): no insistas igual

Código	Qué hacer
`destination_not_allowed`	el destino no está en la lista de contactos. Agrégalo en el panel, si tiene sentido
`session_paused`	la conexión está pausada (por el disyuntor, por ti o por el agente). Reanúdala en el panel
`scope_missing`	la clave no tiene el permiso para esa acción
`action_disabled_by_default`	acción de riesgo alto, apagada por defecto
`first_contact_daily_cap`	se llegó al tope de primeros mensajes del día (a quien nunca habló con el número; el dueño elige el tope en Reglas de envío, hasta 3). Intenta de nuevo después de la hora del campo `quando`; responder a quien ya escribió sigue normal
`cold_requires_optin` / `cold_mass_denied` / `cold_cap_reached`	contacto en frío, solo en modo local: en el servicio alojado quien está fuera de la lista recibe `destination_not_allowed`
`duplicate_content_denied`	el mismo texto ya fue a muchas personas. Varía el texto
`too_many_links`	más de 1 enlace en el mensaje
`auto_reply_cap_conversation`	3 respuestas seguidas sin que la persona vuelva a escribir. Espera a que responda
`conversation_cap_hour` / `conversation_cap_day`	tope de respuestas en esa conversación
`conversation_paused_pingpong`	demasiado ida y vuelta automático. La conversación vuelve cuando escribas en ella
`new_conversations_cap_hour` / `new_conversations_cap_day`	tope de conversaciones nuevas atendidas
`forward_denied`	reenviar un enlace o multimedia de otra persona: aprueba en el panel y repite con el `confirmation_id`
`queue_horizon_exceeded`	solo podría salir dentro de más de 48 horas
`idempotent_replay`	ese mismo pedido ya se decidió; no se reenvió nada. Para repetir a propósito, envía otra `idempotency_key`
`idempotency_conflict`	la misma `idempotency_key` se usó con otro texto

Envío que falló

Código	Qué hacer
`send_failed`	el envío falló y no se entregó nada. Puedes intentarlo de nuevo
`send_uncertain`	no sabemos si salió (WhatsApp no respondió a tiempo). Revisa el chat antes de reenviar; para reenviar de todas formas, usa otra `idempotency_key`
`wa_not_connected` / `telegram_not_connected`	la conexión no está activa. Mira el estado y, si hace falta, vincula de nuevo en el panel

Historial, multimedia y audio (todavía no disponibles)

Código	Qué significa
`history_disabled`	la importación de historial está apagada. Todavía no se puede encender desde el panel
`media_disabled`	la búsqueda de multimedia recibida está apagada. Todavía no se puede encender desde el panel

Editar y borrar

Código	Qué hacer
`message_not_found`	no encontramos ese mensaje en este chat
`not_your_message`	solo puedes editar o borrar un mensaje que Felku envió en ese chat
`key_bound_to_other_channel`	la clave está atada a la otra conexión (WhatsApp o Telegram). Usa una clave de la conexión correcta
`edit_window_closed`	WhatsApp solo deja editar hasta ~15 minutos después del envío
`delete_window_closed`	WhatsApp solo deja borrar para todos hasta ~2 días después del envío

Acceso

HTTP	Código	Qué hacer
401	`unauthorized`	clave ausente, incorrecta, vencida o revocada. Revisa el encabezado `Authorization: Bearer ...`
403	`connection_required`	la clave es válida, pero la cuenta todavía no conectó WhatsApp ni Telegram. Conecta un canal en el panel
403	`not_your_connection`	la clave no puede usar esta conexión (es de otra cuenta)
405	`method_not_allowed`	usa `POST`

Protocolo MCP

Código	Qué significa
`-32602` "Unknown tool"	la herramienta no existe o la clave no tiene su permiso
`-32602` "Invalid arguments"	argumento faltante, de más o fuera de tamaño
`-32020` "Header mismatch"	en la revisión `2026-07-28`, los encabezados `MCP-Protocol-Version`, `Mcp-Method` o `Mcp-Name` no coinciden con el cuerpo
`-32022` "Unsupported protocol version"	una versión de MCP que el servidor no conoce; la respuesta lista las aceptadas

Avisos de conexión

Código	Qué hacer
`linked_devices_others` / `linked_devices_unofficial`	el número tiene otros dispositivos vinculados. En el celular, en Dispositivos vinculados, quita los que no usas: demasiados dispositivos tumban la conexión

Problemas comunes

"El agente no ve las herramientas." Revisa la URL, el encabezado Authorization y que la clave no esté revocada. Si la respuesta es connection_required, conecta un canal en el panel. Pide "lista las herramientas de felku-connect". Si aparecen solo algunas, la clave tiene pocos permisos.
"El agente lee los mismos mensajes cada vez." No está enviando el next_cursor anterior en after.
"El mensaje no salió y no dio error." Mira el acao: adiar quiere decir "todavía no"; el servidor no lo envía solo después.
"Fuera del horario" de noche. El horario de envío vale en la zona horaria de la conexión; el mensaje dice cuál es.
"Dos agentes respondieron el mismo mensaje." Cada clave lee con su propio cursor. Deja solo un agente con permiso de envío por conexión.
"La conexión se cayó." WhatsApp desconecta dispositivos vinculados de vez en cuando. Mira el estado con felku_get_connection_status o en el panel y vincula de nuevo en Conexiones.

Lista completa de códigos

Todos los códigos que el servidor puede devolver, con el texto que acompaña a cada uno. La lista se genera del código del servidor; algunos son raros o internos.

Códigos de acceso, cuenta y servidor (`error.code`)

Código	Texto
`unauthorized`	Clave ausente o inválida.
`forbidden_origin`	Origen no permitido.
`forbidden_host`	Host no permitido.
`bad_request`	Solicitud mal formada.
`not_found`	No encontrado.
`method_not_allowed`	Método HTTP no permitido aquí.
`payload_too_large`	Cuerpo demasiado grande.
`risk_not_accepted`	Hay que aceptar el aviso de riesgo antes de conectar.
`risk_version_outdated`	El aviso de riesgo cambió. Lee la versión actual y acéptala de nuevo antes de conectar.
`allowlist_missing`	Ningún número está permitido para que el agente converse. Añade los números con quienes puede hablar (en el panel; en modo local, FELKU_CONNECT_WA_ALLOW_NUMBERS). Mientras tanto no se lee ni se envía nada.
`invalid_number`	Número o identificador inválido. Usa el teléfono con código de país (ej.: +55 11 91234-5678).
`allowlist_limit`	Llegaste al límite de números de tu plan. Quita uno para añadir otro.
`trial_one_chat`	En la prueba gratis el agente habla con 1 chat de Telegram. Quita el actual para añadir otro, o suscríbete.
`trial_contacts_limit`	En la prueba gratis el agente habla contigo y <limite> contactos más. Quita uno para agregar otro, o suscríbete para liberar más.
`state_unreadable`	estado de seguridad ilegible después de reiniciar; revisa la actividad y reanuda en el panel, en Conexiones
`trial_person_only`	En la prueba gratis el agente solo habla con una persona (chat privado de Telegram). Los grupos y canales de Telegram no se aceptan en ningún plan.
`already_in_list`	Ese número ya está en la lista.
`allowlist_entry_not_found`	Ese elemento no está en tu lista.
`wa_adapter_unavailable`	El adaptador de WhatsApp no está disponible en este servidor.
`wa_not_connected`	WhatsApp no está conectado.
`telegram_not_connected`	Telegram no está conectado. Conecta tu bot en el panel, en Conexiones › Nueva conexión › Telegram.
`unavailable_shared_bot`	Lectura de mensajes no disponible: este bot se comparte con la producción de Felku y la recepción está apagada a propósito.
`invalid_token`	Token del bot inválido.
`telegram_unreachable`	No pude comunicarme con Telegram ahora.
`webhook_conflict`	Este bot tiene un webhook activo; recibir por polling entraría en conflicto. Se detuvo la recepción y no se borró nada.
`unknown_tool`	Herramienta desconocida.
`bad_arguments`	Argumentos inválidos para esta herramienta.
`send_failed`	El envío falló. No se entregó nada.
`send_uncertain`	No sabemos si el mensaje salió (tiempo agotado). Revisa el chat antes de reenviar; para reenviar igualmente, usa otra idempotency_key.
`message_not_found`	No encontré ese mensaje en la bandeja de este chat (o ya pasó su plazo de guarda).
`not_your_message`	Solo se pueden editar o borrar mensajes que Felku envió a este chat.
`edit_window_closed`	Este mensaje ya no se puede editar: en <canal>, la edición vale hasta <janela> después del envío.
`delete_window_closed`	Este mensaje ya no se puede borrar para todos: en <canal>, eso vale hasta <janela> después del envío.
`history_disabled`	El historial importado está desactivado para esta conexión.
`history_notice_required`	Para activar el historial hay que aceptar el aviso.
`history_notice_outdated`	El aviso del historial cambió: lee la versión actual y acepta de nuevo.
`history_chat_not_allowed`	Solo se puede leer el historial de chats de la lista permitida.
`history_no_anchor`	Aún no hay historial de este chat para usar como punto de partida.
`media_disabled`	La recepción de medios está desactivada para esta conexión.
`media_too_large`	Ese medio es demasiado grande para entregarlo.
`media_expired`	El medio expiró: solo está disponible unos minutos después de llegar.
`media_unsupported`	Este tipo de archivo no se puede descargar (solo imágenes, documentos, videos, audio y stickers).
`media_unavailable`	No se pudo obtener ese medio.
`notice_required`	Para activar esto hay que aceptar el aviso.
`notice_outdated`	El aviso cambió: lee la versión actual y acepta de nuevo.
`transcription_unavailable`	La transcripción de audio no está configurada en este servidor.
`transcription_not_in_plan`	Tu plan no incluye transcripción de audio.
`rate_limited`	Demasiadas llamadas. Inténtelo de nuevo en unos instantes.
`internal_error`	Error interno.
`header_mismatch`	Los encabezados HTTP no coinciden con el cuerpo de la solicitud.
`unsupported_protocol_version`	Versión del protocolo MCP no soportada.
`invalid_credentials`	Correo o contraseña incorrectos.
`too_many_attempts`	Demasiados intentos. Espera un poco e inténtalo de nuevo.
`weak_password`	La contraseña debe tener entre 10 y 128 caracteres.
`invalid_email`	Ese correo no parece válido.
`terms_not_accepted`	Debes aceptar los Términos y la Política de Privacidad.
`terms_version_outdated`	Los Términos cambiaron. Recarga la página para ver la versión vigente y acéptala de nuevo.
`invalid_or_expired_token`	Este enlace no es válido o expiró. Solicita uno nuevo.
`invalid_or_expired_code`	Código no válido o expirado. Solicita uno nuevo.
`check_email`	Si el correo puede usarse, enviamos un código.
`session_required`	Inicia sesión en tu cuenta para continuar.
`email_not_verified`	Confirma tu correo para continuar.
`checkout_in_progress`	Ya hay un pago en curso. Termínalo o espera un minuto e inténtalo de nuevo.
`withdrawal_window_closed`	El plazo de <days> días para desistir de la compra ya pasó.
`plan_required`	Elige un plan para continuar.
`billing_state_blocks_action`	El estado de tu suscripción no permite esta acción.
`delete_confirmation_required`	Confirma la eliminación escribiendo la palabra pedida y tu contraseña.
`not_your_connection`	Esta conexión pertenece a otra cuenta.
`connection_required`	Tu clave es válida, pero todavía no hay ningún canal conectado. Conecta WhatsApp o Telegram en el panel (Conexiones › Nueva conexión) antes de usar la clave.
`key_bound_to_other_channel`	Esta clave está atada a otra conexión (WhatsApp o Telegram) y no puede usar las herramientas de este canal.
`key_not_found`	Clave no encontrada.
`accounts_disabled`	Las cuentas no están habilitadas en este servidor.
`service_busy`	Servidor ocupado. Inténtalo de nuevo en un momento.
`downgrade_requires_choice`	Elige qué números se mantienen antes de bajar de plan.
`same_plan`	Este ya es tu plan.

Motivos del envío (`codigo_motivo`)

Código	Texto
`ok`	Se puede enviar.
`invalid_request`	Solicitud inválida: campo <campo>.
`kill_switch_session`	Esta conexión fue apagada por el interruptor de emergencia.
`kill_switch_key`	Esta clave fue apagada por el interruptor de emergencia.
`profile_unknown`	El perfil de límites <perfil> no existe. No se envía nada sin límites.
`scope_missing`	Esta clave no tiene el alcance <escopo>.
`idempotency_key_required`	Un envío real exige una clave de idempotencia (el servidor genera una cuando no la envías).
`idempotent_replay`	Esta solicitud ya fue decidida. No se reenviará nada. Para repetir el mismo mensaje a propósito, envía otra idempotency_key.
`idempotency_conflict`	La misma clave de idempotencia se usó con otro contenido.
`action_disabled_by_default`	La acción <acao> (riesgo <nivel>) viene apagada. Solo un alcance específico de la clave la habilita.
`channel_requires_dedicated_number`	Esta acción solo se permite en un número dedicado.
`session_paused`	La conexión está en pausa (<motivo>). Solo una persona puede reanudarla.
`destination_not_allowed`	Este número no está en tu lista de contactos. Para que el agente hable con él, agrégalo en el panel, en Conexiones, en la pantalla del canal (Con quién puede hablar tu agente).
`allowlist_wildcard_not_allowed`	Este perfil no permite habilitar todos los destinos.
`cold_requires_optin`	Un primer mensaje a alguien que nunca escribió exige confirmar que la persona pidió el contacto.
`cold_mass_denied`	Se negó el envío a lista fría: ya hubo <destinos> destinos fríos en la ventana.
`duplicate_content_denied`	Este contenido ya se envió a <destinos> destinos en las últimas 24 h. El límite existe contra el envío masivo.
`conversation_paused_pingpong`	Esta conversación se pausó por intercambios automáticos repetidos. El dueño debe hablar para liberarla.
`auto_reply_cap_conversation`	Límite de <max> respuestas automáticas seguidas sin un mensaje nuevo de la persona.
`conversation_cap_hour`	Límite de <teto> respuestas por hora en esta conversación.
`conversation_cap_day`	Límite de <teto> respuestas por día en esta conversación.
`new_conversations_cap_hour`	Límite de <teto> conversaciones nuevas atendidas por hora. Quien ya está en conversación no se ve afectado.
`new_conversations_cap_day`	Límite de <teto> conversaciones nuevas atendidas por día. Quien ya está en conversación no se ve afectado.
`cadence_variation`	El ritmo de los envíos era demasiado regular; este se retrasó un poco para variarlo.
`linked_devices_unofficial`	Este número ya tiene <count> dispositivo(s) vinculado(s) no oficial(es). Quite los que no use: demasiados dispositivos tumban la conexión.
`linked_devices_others`	Este número tiene <count> otro(s) dispositivo(s) vinculado(s). Revise Dispositivos vinculados y quite los que no use: demasiados dispositivos tumban la conexión.
`reply_other_chat_needs_confirmation`	Responder a un tercero en otro chat exige la confirmación del dueño.
`forward_denied`	Un enlace o medio recibido de un tercero no se reenvía a otro chat sin confirmación.
`outside_send_window`	Fuera del horario de envío. Inténtalo de nuevo después de las <hora> (<fuso>).
`pacing_wait`	Esperando el intervalo mínimo entre envíos.
`burst_pause`	Pausa después de una ráfaga de envíos.
`cap_hour_reached`	Límite por hora alcanzado (<usado> de <teto>).
`cap_day_reached`	Límite diario alcanzado (<usado> de <teto>).
`cold_cap_reached`	Límite de primeros mensajes alcanzado (<usado> de <teto>).
`first_contact_daily_cap`	Ya enviaste <usado> primeros mensajes hoy (el tope es <teto> por día, igual en todos los planes). Se libera de nuevo a las <volta> (<fuso>). Responder a quien ya escribió sigue normal.
`group_rate_limited`	Límite de <max> operaciones de grupo en la ventana. Espere.
`limit_zero`	Este límite está en cero en este perfil: la acción está desactivada.
`queue_horizon_exceeded`	La espera superaría el límite de la cola. Se negó la solicitud.
`too_many_links`	Mensaje con <links> enlaces; el máximo es <max>.
`loop_echo_discarded`	Eco de un mensaje enviado por nosotros, descartado.
`owner_outbound_ignored`	El mensaje del dueño a un tercero no es entrada para el agente.
`history_not_delivered`	El historial o los mensajes sin conexión no se entregan al agente.
`inbound_expired`	El mensaje es demasiado antiguo para entregarse al agente.
`duplicate_inbound`	Mensaje repetido, ignorado.
`inbound_filtered`	Este tipo de entrada no se entrega al agente (grupo, estado, canal, reacción, edición o llamada).
`already_claimed`	Otro agente ya asumió la respuesta a este mensaje.
`lid_unresolved`	No se pudo identificar al remitente (identificador LID sin correspondencia).