Errors and reasons

Every send response has a stable codigo_motivo, for the agent to decide what to do, and a message, for people. Access and server errors come with error.code and retryable (whether it's worth trying again).

Send delayed (`adiar`): try again after `quando`

Code	Why
`outside_send_window`	outside the sending hours the owner turned on (default 08:00 to 21:00 on WhatsApp; 07:00 to 23:00 on Telegram; in the connection's time zone). The message says the time: "try again after HH:MM"
`pacing_wait`	still within the minimum interval between sends
`burst_pause`	pause after a burst of sends
`cap_hour_reached` / `cap_day_reached`	hourly or daily cap reached
`cadence_variation`	rhythm too regular; delayed a moment
`reply_other_chat_needs_confirmation`	sending to another chat right after reading a message from someone else: approve in the dashboard and repeat with the `confirmation_id`

Send denied (`negar`): don't insist the same way

Code	What to do
`destination_not_allowed`	the destination isn't on the contact list. Add it in the dashboard, if it makes sense
`session_paused`	the connection is paused (by the circuit breaker, by you or by the agent). Resume it in the dashboard
`scope_missing`	the key doesn't have the permission for this action
`action_disabled_by_default`	high-risk action, switched off by default
`first_contact_daily_cap`	the day's first-message cap was reached (to people who never talked to the number; the owner picks the cap in Sending rules, up to 3). Try again after the time in the `quando` field; replying to people who already wrote works as usual
`cold_requires_optin` / `cold_mass_denied` / `cold_cap_reached`	cold contact, local mode only: in the hosted service anyone off the list gets `destination_not_allowed`
`duplicate_content_denied`	the same text already went to many people. Vary the text
`too_many_links`	more than 1 link in the message
`auto_reply_cap_conversation`	3 replies in a row without the person writing again. Wait for them to reply
`conversation_cap_hour` / `conversation_cap_day`	reply cap for this conversation
`conversation_paused_pingpong`	too much automatic back-and-forth. The conversation resumes when you write in it
`new_conversations_cap_hour` / `new_conversations_cap_day`	cap of new conversations served
`forward_denied`	forwarding someone else's link or media: approve in the dashboard and repeat with the `confirmation_id`
`queue_horizon_exceeded`	it could only go out more than 48 hours from now
`idempotent_replay`	this same request was already decided; nothing was resent. To repeat on purpose, send a different `idempotency_key`
`idempotency_conflict`	the same `idempotency_key` was used with a different text

Send that failed

Code	What to do
`send_failed`	the send failed and nothing was delivered. You can try again
`send_uncertain`	we don't know whether it went out (WhatsApp didn't answer in time). Check the chat before resending; to resend anyway, use a different `idempotency_key`
`wa_not_connected` / `telegram_not_connected`	the connection isn't up. Check the status and, if needed, pair again in the dashboard

History, media and audio (not available yet)

Code	What it means
`history_disabled`	history import is switched off. It can't be switched on from the dashboard yet
`media_disabled`	fetching received media is switched off. It can't be switched on from the dashboard yet

Edit and delete

Code	What to do
`message_not_found`	we didn't find that message in this chat
`not_your_message`	you can only edit or delete a message Felku sent in this chat
`key_bound_to_other_channel`	the key is tied to the other connection (WhatsApp or Telegram). Use a key for the right connection
`edit_window_closed`	WhatsApp only allows editing up to ~15 minutes after sending
`delete_window_closed`	WhatsApp only allows deleting for everyone up to ~2 days after sending

Access

HTTP	Code	What to do
401	`unauthorized`	key missing, wrong, expired or revoked. Check the `Authorization: Bearer ...` header
403	`connection_required`	the key is valid, but the account hasn't connected WhatsApp or Telegram yet. Connect a channel in the dashboard
403	`not_your_connection`	the key can't use this connection (it belongs to another account)
405	`method_not_allowed`	use `POST`

MCP protocol

Code	What it means
`-32602` "Unknown tool"	the tool doesn't exist or the key doesn't have its permission
`-32602` "Invalid arguments"	argument missing, extra or out of size
`-32020` "Header mismatch"	on revision `2026-07-28`, the `MCP-Protocol-Version`, `Mcp-Method` or `Mcp-Name` headers don't match the body
`-32022` "Unsupported protocol version"	an MCP version the server doesn't know; the response lists the accepted ones

Connection warnings

Code	What to do
`linked_devices_others` / `linked_devices_unofficial`	the number has other linked devices. On the phone, under Linked devices, remove the ones you don't use: too many devices drop the connection

Common problems

"The agent doesn't see the tools." Check the URL, the Authorization header and that the key wasn't revoked. If the answer is connection_required, connect a channel in the dashboard. Ask "list the felku-connect tools". If only some show up, the key has few permissions.
"The agent reads the same messages every time." It isn't sending the previous next_cursor in after.
"The message didn't go out and there was no error." Look at acao: adiar means "not yet"; the server doesn't send it later on its own.
"Outside hours" at night. Sending hours apply in the connection's time zone; the message says which one.
"Two agents replied to the same message." Each key reads with its own cursor. Give send permission to only one agent per connection.
"The connection dropped." WhatsApp drops linked devices from time to time. Check the state with felku_get_connection_status or in the dashboard and pair again under Connections.

Full list of codes

Every code the server can return, with the text that comes with it. The list is generated from the server code; some are rare or internal.

Access, account and server codes (`error.code`)

Code	Text
`unauthorized`	Missing or invalid key.
`forbidden_origin`	Origin not allowed.
`forbidden_host`	Host not allowed.
`bad_request`	Malformed request.
`not_found`	Not found.
`method_not_allowed`	HTTP method not allowed here.
`payload_too_large`	Request body too large.
`risk_not_accepted`	You must accept the risk notice before connecting.
`risk_version_outdated`	The risk notice has changed. Read the current version and accept it again before connecting.
`allowlist_missing`	No number is allowed for the agent to talk to. Add the numbers it may talk to (in the panel; in local mode, FELKU_CONNECT_WA_ALLOW_NUMBERS). Until then nothing is read or sent.
`invalid_number`	Invalid number or identifier. Use the phone number with country code (e.g. +55 11 91234-5678).
`allowlist_limit`	You reached your plan's limit of numbers. Remove one to add another.
`trial_one_chat`	During the free trial the agent talks to 1 Telegram chat. Remove the current one to add another, or subscribe.
`trial_contacts_limit`	On the free trial the agent talks with you and <limite> more contacts. Remove one to add another, or subscribe to unlock more.
`state_unreadable`	safety state unreadable after a restart; check the activity and resume in the dashboard, under Connections
`trial_person_only`	During the free trial the agent only talks to one person (a private Telegram chat). Telegram groups and channels are not supported on any plan.
`already_in_list`	That number is already on the list.
`allowlist_entry_not_found`	That entry is not on your list.
`wa_adapter_unavailable`	The WhatsApp adapter is not available on this server.
`wa_not_connected`	WhatsApp is not connected.
`telegram_not_connected`	Telegram is not connected. Connect your bot in the dashboard, under Connections > New connection > Telegram.
`unavailable_shared_bot`	Reading messages is unavailable: this bot is shared with Felku production and receiving is turned off on purpose.
`invalid_token`	Invalid bot token.
`telegram_unreachable`	Could not reach Telegram right now.
`webhook_conflict`	This bot has an active webhook; receiving by polling would conflict. Receiving was stopped and nothing was deleted.
`unknown_tool`	Unknown tool.
`bad_arguments`	Invalid arguments for this tool.
`send_failed`	The send failed. Nothing was delivered.
`send_uncertain`	We can't tell whether the message was sent (timed out). Check the chat before resending; to resend anyway, use a different idempotency_key.
`message_not_found`	I couldn't find that message in this chat's inbox (or its storage period has already passed).
`not_your_message`	Only messages that Felku sent to this chat can be edited or deleted.
`edit_window_closed`	This message can no longer be edited: on <canal>, editing is allowed up to <janela> after sending.
`delete_window_closed`	This message can no longer be deleted for everyone: on <canal>, that's allowed up to <janela> after sending.
`history_disabled`	Imported history is turned off for this connection.
`history_notice_required`	Turning on history requires accepting the notice.
`history_notice_outdated`	The history notice changed: read the current version and accept again.
`history_chat_not_allowed`	History can only be read for chats on the allowlist.
`history_no_anchor`	There is no history for this chat yet to use as a starting point.
`media_disabled`	Receiving media is turned off for this connection.
`media_too_large`	That media is too large to be delivered.
`media_expired`	The media has expired: it is only available for a few minutes after it arrives.
`media_unsupported`	This kind of media can't be downloaded (only images, documents, videos, audio and stickers).
`media_unavailable`	That media could not be retrieved.
`notice_required`	Turning this on requires accepting the notice.
`notice_outdated`	The notice changed: read the current version and accept again.
`transcription_unavailable`	Audio transcription is not configured on this server.
`transcription_not_in_plan`	Your plan does not include audio transcription.
`rate_limited`	Too many calls. Try again shortly.
`internal_error`	Internal error.
`header_mismatch`	The HTTP headers do not match the request body.
`unsupported_protocol_version`	Unsupported MCP protocol version.
`invalid_credentials`	Incorrect email or password.
`too_many_attempts`	Too many attempts. Wait a little and try again.
`weak_password`	The password must be between 10 and 128 characters.
`invalid_email`	That email doesn't look valid.
`terms_not_accepted`	You must accept the Terms and the Privacy Policy.
`terms_version_outdated`	The Terms changed. Reload the page to see the current version and accept again.
`invalid_or_expired_token`	This link is invalid or has expired. Request a new one.
`invalid_or_expired_code`	Invalid or expired code. Request a new one.
`check_email`	If the email can be used, we sent a code to it.
`session_required`	Sign in to your account to continue.
`email_not_verified`	Confirm your email to continue.
`checkout_in_progress`	A checkout is already in progress. Finish it or wait a minute and try again.
`withdrawal_window_closed`	The <days>-day period to withdraw from the purchase has passed.
`plan_required`	Choose a plan to continue.
`billing_state_blocks_action`	Your subscription state doesn't allow this action.
`delete_confirmation_required`	Confirm the deletion by typing the requested word and your password.
`not_your_connection`	This connection belongs to another account.
`connection_required`	Your key is valid, but no channel is connected yet. Connect WhatsApp or Telegram in the Felku panel (Connections > New connection) before using this key.
`key_bound_to_other_channel`	This key is tied to a different connection (WhatsApp or Telegram) and cannot use this channel's tools.
`key_not_found`	Key not found.
`accounts_disabled`	Accounts are not enabled on this server.
`service_busy`	Server busy. Try again in a moment.
`downgrade_requires_choice`	Choose which numbers to keep before downgrading.
`same_plan`	This is already your plan.

Send reasons (`codigo_motivo`)

Code	Text
`ok`	Clear to send.
`invalid_request`	Invalid request: field <campo>.
`kill_switch_session`	This connection was turned off by the kill switch.
`kill_switch_key`	This key was turned off by the kill switch.
`profile_unknown`	The limits profile <perfil> does not exist. Nothing is sent without limits.
`scope_missing`	This key does not have the scope <escopo>.
`idempotency_key_required`	A real send requires an idempotency key (the server generates one when you do not send it).
`idempotent_replay`	This request was already decided. Nothing will be sent again. To repeat the same message on purpose, send a different idempotency_key.
`idempotency_conflict`	The same idempotency key was used with different content.
`action_disabled_by_default`	The action <acao> (<nivel> risk) is off by default. Only a specific key scope enables it.
`channel_requires_dedicated_number`	This action is only allowed on a dedicated number.
`session_paused`	The connection is paused (<motivo>). Only a person can resume it.
`destination_not_allowed`	This number is not on your contact list. For the agent to talk to it, add it in the dashboard, under Connections, on the channel screen (Who your agent can talk to).
`allowlist_wildcard_not_allowed`	This profile does not allow all destinations.
`cold_requires_optin`	A first message to someone who never wrote requires confirmation that they asked to be contacted.
`cold_mass_denied`	Cold-list sending was denied: there were already <destinos> cold destinations in the window.
`duplicate_content_denied`	This content was already sent to <destinos> destinations in the last 24 h. The limit exists to prevent mass messaging.
`conversation_paused_pingpong`	This conversation was paused because of repeated automatic exchanges. The owner must speak to release it.
`auto_reply_cap_conversation`	Limit of <max> automatic replies in a row without a new message from the person.
`conversation_cap_hour`	Limit of <teto> replies per hour in this conversation.
`conversation_cap_day`	Limit of <teto> replies per day in this conversation.
`new_conversations_cap_hour`	Limit of <teto> new conversations served per hour. People already in a conversation are unaffected.
`new_conversations_cap_day`	Limit of <teto> new conversations served per day. People already in a conversation are unaffected.
`cadence_variation`	Sends were arriving at a too-regular rhythm; this one was delayed a little to vary it.
`linked_devices_unofficial`	This number already has <count> unofficial linked device(s). Remove the ones you do not use: too many devices bring the connection down.
`linked_devices_others`	This number has <count> other linked device(s). Check Linked devices and remove the ones you do not use: too many devices bring the connection down.
`reply_other_chat_needs_confirmation`	Replying to a third party in a different chat requires the owner's confirmation.
`forward_denied`	A link or media received from a third party is not forwarded to another chat without confirmation.
`outside_send_window`	Outside the sending hours. Try again after <hora> (<fuso>).
`pacing_wait`	Waiting for the minimum interval between sends.
`burst_pause`	Pause after a burst of sends.
`cap_hour_reached`	Hourly limit reached (<usado> of <teto>).
`cap_day_reached`	Daily limit reached (<usado> of <teto>).
`cold_cap_reached`	First-message limit reached (<usado> of <teto>).
`first_contact_daily_cap`	You already sent <usado> first messages today (the cap is <teto> per day, the same on every plan). It opens again at <volta> (<fuso>). Replying to people who already wrote keeps working as usual.
`group_rate_limited`	Limit of <max> group operations in the window. Please wait.
`limit_zero`	This limit is zero in this profile: the action is disabled.
`queue_horizon_exceeded`	The wait would exceed the queue limit. The request was denied.
`too_many_links`	Message with <links> links; the maximum is <max>.
`loop_echo_discarded`	Echo of a message we sent, discarded.
`owner_outbound_ignored`	The owner's message to a third party is not input for the agent.
`history_not_delivered`	History or offline messages are not delivered to the agent.
`inbound_expired`	The message is too old to be delivered to the agent.
`duplicate_inbound`	Duplicate message, ignored.
`inbound_filtered`	This kind of input is not delivered to the agent (group, status, channel, reaction, edit or call).
`already_claimed`	Another agent already took the reply to this message.
`lid_unresolved`	The sender could not be identified (LID identifier with no match).