Error reference
When the dashboard, widget or API returns an error, the response body often includes code and doc fields linking here. Find the code below: each entry lists a typical cause and concrete fix steps.
Quick links by code
Sign-in and account
Authorization, email verification, and registration.
auth_required
HTTP 401 · Sign-in required
Sign in to your account to continue.
Why this happens
- The request ran without an active session or with an expired login.
- Some API endpoints are available only to the client owner (dashboard).
What to do
- Open the sign-in page and authenticate with your email.
- If you are already signed in — refresh the page or sign out and sign in again.
email_not_verified
HTTP 403 · Email not verified
Sign-in is allowed only after confirming the email with the code from the letter.
Why this happens
- Registration started, but the email code has not been entered yet.
What to do
- Finish registration on the Sign-up page and enter the code within 15 minutes.
- If there is no email — check Spam or request the code again.
email_already_registered
HTTP 400 · Email already registered
An account with this email already exists.
Why this happens
- One email can be linked to only one account.
What to do
- Sign in via the login page.
- For a new account, use a different email.
registration_otp_invalid
HTTP 400 · Invalid code
The code from the email did not match.
Why this happens
- A typo in the digits, an old code, or too many attempts.
What to do
- Check the 6 digits from the latest email with no spaces.
- Click “Resend code” and enter the digits from the new email.
registration_otp_expired
HTTP 400 · Code expired
The email code is no longer valid — more than 15 minutes have passed since it was sent.
Why this happens
- Verification codes are time-limited for security.
What to do
- Click “Resend code” and enter the digits from the new email.
registration_resend_cooldown
HTTP 429 · Resend too frequent
You can resend the code email no sooner than after one minute.
Why this happens
- A pause between emails protects the mailbox from spam.
What to do
- Wait a bit, check Spam, then click “Resend code”.
Widget and agent
Widget readiness, subscription, prompt, and knowledge base.
client_not_found
HTTP 404 · Client or widget not found
The specified client does not exist or was deleted.
Why this happens
- The request used an incorrect client (widget) id.
- The dashboard is calling a foreign or outdated clientId.
What to do
- In the Widget section, copy the current install code with the correct clientId.
- Confirm the widget is embedded from the same project as your account.
subscription_required
HTTP 403 · Subscription required for the widget
On the free plan without a trial the widget is unavailable.
Why this happens
- FREE plan without an active trial does not include the public widget.
What to do
- Subscribe or activate a trial in the Plans section.
bot_disabled
HTTP 403 · Agent is off (site chat)
A visitor wrote in the widget, but the agent is disabled in settings.
Why this happens
- The agent activity flag (isActive) is off — public chat does not process messages.
What to do
- Dashboard → Widget or Agent settings → enable the agent and save.
- Check the widget on the site after settings publish.
widget_disabled
HTTP 403 · Agent is off (dashboard diagnostics)
Widget check in the dashboard: the agent is inactive.
Why this happens
- “Check widget” diagnostics found the agent activity flag is off.
- Same toggle as bot_disabled in chat, but the context is a dashboard report, not a visitor reply.
What to do
- Dashboard → Widget → enable the agent and run the check again.
prompt_invalid
HTTP 400 · System prompt is missing
The prompt is too short or contains invalid characters.
Why this happens
- The agent needs a meaningful system prompt to answer.
What to do
- Agent settings → main settings — fill in the system prompt (from 10 characters) and save.
no_knowledge
HTTP 400 · No knowledge base
No documents, FAQ, or site crawl are loaded.
Why this happens
- The agent has nothing to ground answers on.
What to do
- Knowledge base: upload documents, FAQ, run a site crawl, or fill in the brief.
telegram_same_bot_notifications
HTTP 400 · Same bot for chat and alerts
The notifications bot token matches the agent bot.
Why this happens
- Technically one bot cannot be both the “dialog agent” and “leads-only alerts” bot at once.
What to do
- Create a second bot in @BotFather for lead alerts.
- Put its token on the notifications page; keep the agent token in messenger integrations.
Limits and load
Plan limits and protection against frequent requests.
LIMIT_REACHED
HTTP 429 · Dialog limit for the plan
The monthly dialog limit on the current plan is exhausted.
Why this happens
- Each new conversation (new chat session) increments the counter.
- The limit comes from the plan; during trial it may match the Business plan limit.
What to do
- Open Plans and upgrade, or wait for the counter reset (~every 30 days from the reset date).
- After payment, limits refresh without waiting for the calendar month end.
RATE_LIMIT
HTTP 429 · Too many requests
Messages are being sent to the chat too frequently from your side.
Why this happens
- Abuse protection: only a limited number of requests are allowed in a short interval.
What to do
- Wait about a minute and send the message again.
- Do not use scripts or auto-send into the same chat.
Message security
Moderation, prompt injection, and SQL-like patterns.
BLOCKED_CONTENT
HTTP 429 · Message blocked by moderation
The text fails the platform’s prohibited-topics filter.
Why this happens
- Content policy matched themes or wording the platform does not allow.
- Unlike INJECTION, this blocks topical content, not an attempt to override bot instructions.
What to do
- Rephrase the question neutrally, without banned words or suspicious links.
- On a false positive, send support the exact message text and request time.
INJECTION
HTTP 429 · Suspected prompt injection
This request cannot be processed — it looks like an attempt to change the assistant’s rules.
Why this happens
- The text contains model commands such as “forget instructions”, “answer as…”, system tags, or similar patterns.
- In the site widget such a request usually gets a polite refusal (HTTP 200). INJECTION is more often visible in API and integrations.
What to do
- Ask a normal question about a product, service, or order — without telling the assistant how to behave.
- For role and style tests, use agent settings in the dashboard, not visitor chat commands.
SQL_INJECTION
HTTP 429 · Message rejected
The text looks like a SQL injection and is not accepted.
Why this happens
- The message contains constructs typical of database attacks.
What to do
- Remove SQL-like fragments and ask again in plain language.
Phone and website
Profile fields and quick start.
phone_required
HTTP 400 · Phone is required
The phone field is required for this step.
Why this happens
- A number is required to finish the profile or request.
What to do
- Fill in the phone field and save again.
phone_invalid
HTTP 400 · Invalid phone number
The number was not recognized as valid.
Why this happens
- Wrong format, a typo, or a number outside the +7 zone.
What to do
- Enter a mobile number as +7… or 8… / 9… — as hinted in the form.
phone_zone_ru_kz
HTTP 400 · Russia or Kazakhstan number required
Only +7 zone numbers (RU and KZ) are accepted.
Why this happens
- The product targets this numbering zone.
What to do
- Enter a +7 number or choose another contact method if the form offers one.
phone_template_not_allowed
HTTP 400 · Test or template number
That number cannot be used for registration.
Why this happens
- A known placeholder or repeating pattern was detected (for example identical digits).
What to do
- Provide a real contact number where you can be reached.
phone_already_used
HTTP 400 · Number already in use
This number is already linked to another account.
Why this happens
- One phone number can be attached to only one client.
What to do
- Use your own contact number, or contact support if this number is yours.
website_required
HTTP 400 · Website URL is required
Enter the company website address.
Why this happens
- The URL field is empty, but this step requires a value.
What to do
- Enter a full address, for example https://example.com
website_invalid_url
HTTP 400 · Invalid URL
The string is not a valid link.
Why this happens
- A typo, spaces, or invalid characters in the address.
What to do
- Copy the address from the browser (with https://) and paste it into the field.
website_protocol_invalid
HTTP 400 · http or https required
Only http and https protocols are allowed.
Why this happens
- Another protocol was specified (ftp, file, etc.).
What to do
- Replace the link with https://…
website_placeholder
HTTP 400 · Test or reserved domain
You cannot use example.com, localhost, and similar addresses.
Why this happens
- These domains are reserved for documentation and are not a company site.
What to do
- Enter the real production domain of your website.
Promo codes and billing
Activating discounts and gift subscriptions.
promo_not_found
HTTP 400 · Promo code not found
There is no such promo code — check the spelling.
Why this happens
- A typo in the code, or the promo has not been created in admin yet.
What to do
- Check spelling (case does not matter).
- Confirm a valid code with support.
promo_not_active
HTTP 400 · Promo code not active yet
The promo code start date has not arrived.
Why this happens
- The promo settings specify a future “from” date.
What to do
- Wait for the start date or use another promo code.
promo_expired
HTTP 400 · Promo code expired
The promo code validity period has ended.
Why this happens
- The promo code has an end date.
What to do
- Ask support for a new code or pay without a discount.
promo_exhausted
HTTP 400 · Promo code exhausted
The usage limit has been reached.
Why this happens
- The promo code has a limited number of activations.
What to do
- Use another code or a plan without a promo.
promo_plan_mismatch
HTTP 400 · Promo code is for another plan
The promo code is tied to a different plan.
Why this happens
- Promo settings restrict it to a specific plan.
What to do
- Choose the plan the promo applies to, or pay without a code.
promo_subscription_only
HTTP 400 · This is a subscription promo
Activate it with a separate button, not during payment.
Why this happens
- SUBSCRIPTION promo type is incompatible with creating a payment.
What to do
- Use the gift-subscription activation flow for this promo code.
Email delivery
SMTP and verification code delivery.
mail_not_configured
HTTP 503 · Mail is not configured
The verification email cannot be sent right now — the mail service is temporarily unavailable.
Why this happens
- SMTP parameters are not set on the server (admin technical setting).
What to do
- Try again in a few minutes. If it persists — contact support.
- For admins: set SMTP_HOST, SMTP_PORT, EMAIL_FROM and if needed SMTP_USER, SMTP_PASS.
mail_send_failed
HTTP 502 · Failed to send email
The verification email could not be delivered.
Why this happens
- The mail server rejected the send, the network was unavailable, or provider limits hit.
What to do
- Wait a minute and click “Resend code”.
- Check Spam and that the email address is correct.
System errors
Server failures and general form validation.
server_error
HTTP 500 · Service error (checks and background jobs)
The server could not finish a check or background operation.
Why this happens
- Failure during widget diagnostics, site crawl, or another background task.
What to do
- Retry the check in a few minutes.
- If it repeats — contact support with the time and dashboard section.
internal_error
HTTP 500 · Form processing error
The action could not be completed — registration, saving settings, or another dashboard step.
Why this happens
- An unexpected exception occurred on the server while handling your request.
What to do
- Refresh the page and try again.
- If that does not help — contact support and say what you were doing before the error.
validation_failed
HTTP 400 · Form data failed validation
Check the fields — one of the values is incorrect.
Why this happens
- One or more fields do not match the required format or constraints.
What to do
- Read the error next to the field or in the notification and correct the value.