NeuronChat
Start free
Sections

reference

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.

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

  1. Open the sign-in page and authenticate with your email.
  2. 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

  1. Finish registration on the Sign-up page and enter the code within 15 minutes.
  2. 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

  1. Sign in via the login page.
  2. 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

  1. Check the 6 digits from the latest email with no spaces.
  2. 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

  1. 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

  1. 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

  1. In the Widget section, copy the current install code with the correct clientId.
  2. 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

  1. 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

  1. Dashboard → Widget or Agent settings → enable the agent and save.
  2. 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

  1. 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

  1. 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

  1. 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

  1. Create a second bot in @BotFather for lead alerts.
  2. 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

Plan tokens have run out

The monthly token limit on the current plan is exhausted.

Why this happens

  • Every agent reply spends tokens: the longer the conversation and the knowledge base and the more powerful the model, the more it spends.
  • The token limit comes from the plan and renews every 30 days; a purchased token pack never expires.

What to do

  1. Open Plans: buy a token pack, upgrade, or wait for the limit to renew (every 30 days).
  2. 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

  1. Wait about a minute and send the message again.
  2. 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

  1. Rephrase the question neutrally, without banned words or suspicious links.
  2. 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

  1. Ask a normal question about a product, service, or order — without telling the assistant how to behave.
  2. 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

  1. 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

  1. 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

  1. 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

  1. 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

  1. 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

  1. 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

  1. 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

  1. 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

  1. 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

  1. 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

  1. Check spelling (case does not matter).
  2. 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

  1. 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

  1. 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

  1. 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

  1. 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

  1. Use the gift-subscription activation flow for this promo code.

promo_already_used

HTTP 400

Promo code already used

This promo code has already been applied to a payment on your account.

Why this happens

  • A discount promo code works once per customer — for card payments and invoices alike.

What to do

  1. Pay without the promo code or ask support for a new one.

promo_empty

HTTP 400

Enter a promo code

The promo code field is empty.

Why this happens

  • No promo code was provided.

What to do

  1. Enter a code or pay without one.

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

  1. Try again in a few minutes. If it persists — contact support.
  2. 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

  1. Wait a minute and click “Resend code”.
  2. 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

  1. Retry the check in a few minutes.
  2. 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

  1. Refresh the page and try again.
  2. 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

  1. Read the error next to the field or in the notification and correct the value.