Help

Troubleshooting

The messages and symptoms people hit most in the portal and on the API, one table per area, each with its likely cause, the fix, and the page that explains it in full.

Every message the portal or the API can show is explained on the page of the feature that shows it. This page collects the ones people hit most, one table per area, so you can find the words on your screen, read the likely cause and the fix in one line each, and open the full entry when you need more. Use your browser's find on this page with the exact text you see.

A symptom in bold is the exact text the portal or the API shows. A symptom in plain text describes what you see when there is no message. The Page column opens the full entry, with everything this table leaves out.

Sign-in and account

Symptom Likely cause What to do Page
Invalid credentials The email or username and the password do not match an account, or the account was created with Google or Microsoft and has no password. Check both for a typo, use Forgot Your Password?, or sign in with the Continue with button the account was created with. Sign-in methods
User not confirmed The account exists, but its email has not been verified. Open the verification email, press Open the verify page and then Verify Email, or request a new code with Resend. Sign-in methods
Invalid verification code The six digits do not match the latest code sent; after 5 wrong attempts the code is discarded. Press Resend and use the newest message. Sign-in methods
No active code found or code has expired The code is older than its life, or a newer code has replaced it. Request a new one. Sign-in methods
Duplicate value for email The address already has an account, whatever method created it. Sign in with that account, or use another address. Sign up and create your workspace
Invalid code At sign-in or when disabling two-factor authentication, neither a current app code nor an unused recovery code matched. Check the app's entry is the one for this account, wait for the next code, or switch to Lost your device? Use a recovery code. Two-factor authentication
Setup session expired; please restart enrollment More than 10 minutes passed between pressing Enable and confirming the code. Close the dialog, press Enable again and scan the new QR code, not the old one. Two-factor authentication

Billing

Symptom Likely cause What to do Page
Could not start checkout. The purchase could not be opened; the text carries the reason when there is one. Click Back to plans and try again. If the reason says the workspace already has an active subscription, use the plan card's Upgrade or Downgrade button instead. Choose or change your plan
Subscription is canceled but still active until period ends. Use reactivate instead. You canceled and the period has not ended. Click Reactivate Plan on the Subscription page instead of Select Plan. Choose or change your plan
You lack the required permission(s): billing.manage Your role cannot change the subscription or open invoices. Ask the workspace Owner. Choose or change your plan
Payment Failed You returned from PayPal without an approved payment. Try Again reopens checkout on PayPal; Change Payment Method reopens it on a card tab (Stripe or Paymob). Pay and manage your payment method
Confirmation failed The payment could not be matched to your workspace. Click Go to Subscription; if the page still shows the old plan after a reload, contact support with the time of the payment. Pay and manage your payment method
Could not confirm your credit purchase. The top-up could not be confirmed at once; if you were charged, the credits appear within a few minutes. Reload the Subscription page after a few minutes before buying again. Pay and manage your payment method
Balance after does not match the sidebar The sidebar counts plan credits only; Balance after adds the extra credits. Compare it with the large figure on the Credit balance card on the Subscription page. Track your credit usage

Text to Speech

Symptom Likely cause What to do Page
The generate button is greyed out The writing area holds only whitespace, the voice list has not finished loading, or a generation is already running. Type some text, or wait a moment. Generate speech
Error: Insufficient subscription balance The workspace balance cannot cover the charge; nothing was charged and nothing was generated. Add credits under Subscription, then click Generate again. Generate speech
Error: Speech generation is temporarily unavailable. Please try again. The generation did not run; the charge has already been returned to the balance. Wait a short while and generate again. Generate speech
Error: Voice not found The selected voice has been withdrawn. Click Change voice and pick another one. Generate speech
Error: text must be shorter than or equal to 5000 characters The text grew past 5,000 characters after Tashkeel, because each diacritic counts as a character. Shorten the text and generate again. Generate speech
The Tashkeel switch is not there or is greyed out No voice is selected, the voice is an English one, or the text has no Arabic letters. Click Change voice, pick an Arabic voice and type Arabic text. Add diacritics
Nothing changed after the spinner stopped The text has no Arabic, every word already carried a mark, or you edited the text while the marks were being added. Stop typing, then switch Tashkeel off and on again. Add diacritics
The audio plays but Download gives a file you cannot open The file is WAV, and the tool that refuses it expects MP3. Convert the WAV with a tool of your choice. Quickstart: your first speech file

Speech to Text and Sound Cleaning

Symptom Likely cause What to do Page
Please upload one of: MP3, WAV, FLAC, OGG, M4A, AAC, WEBM. The file's extension is not one of the seven. Export the audio in one of them; renaming the file is not enough. Transcribe a file
Audio must be 1 hour or shorter. The recording is longer than the page accepts. Split the recording and transcribe each part. Transcribe a file
Transcription is temporarily unavailable. Please try again. The file could not be handed over for transcription; the charge is refunded. Press Try again once; if it repeats, wait a few minutes. Transcribe a file
Job timed out — AI server did not respond No transcript arrived within 10 minutes of the file being accepted; the charge is refunded. Transcribe a shorter file, or split this one. Transcribe a file
The transcript reads Your transcription will appear here. The transcription finished with no text; it is charged as a completed transcription. Check that the recording contains speech at an audible level, then transcribe it again. Read a transcript
That clip is longer than 1 hour. Split it and try again. The recording is longer than 1 hour. Split it into parts of 1 hour or less and clean each part. Clean a recording
Sound cleaning is temporarily unavailable. Please try again. The run could not be completed, or took longer than 10 minutes; the charge was refunded. Wait a moment and click Try again. Clean a recording
Cleaning stopped before it finished. Try again. The connection dropped before a result arrived. Reload the page: if the file is under Recent cleanups, it finished and was charged; if not, nothing was charged, so check your connection and drop it again. Clean a recording

Agents

Symptom Likely cause What to do Page
Plan limit reached The workspace has as many live agents as its plan allows; archived agents are not counted. Archive an agent you are not using, or upgrade. Create an agent
This agent is archived. Restore it first to make changes. You are editing an archived agent. Use Restore in the header, then edit. Write the persona
This model is no longer available. Pick another to keep this agent working. The model saved on this agent is not in the current list. Pick a current model. Choose a model and reasoning effort
Storage limit exceeded for this workspace. Delete files or upgrade your plan. Your plan's storage allowance is full. Delete sources you no longer need, or move to a larger plan. Add documents to the library
A knowledge row says Failed Scanned PDFs with no text layer and password-protected files are the common causes. Open the row to read the reason, fix the document, delete the row and upload it again. Add documents to the library
Everything is Ready and selected but the agent still misses it The caller's words do not appear in the document. Ask with words from the document as a test; if that works, lower the threshold or add the caller's phrasing to the document. The agent did not use my document
The agent invents an answer instead of saying it does not know Retrieval returning nothing does not stop the model answering; that behaviour comes from Personality. Add an instruction there telling it to say it does not know when it has no source. The agent did not use my document
No reply. Try again. Sixty seconds passed between your message and the first word of the answer; a slow tool call and a slow model both look like this. Send again; afterwards, check the conversation for a tool call that did not return. Test your agent
Could not start the voice session. The workspace has no credits, or the agent was archived in another tab. Check both, close the playground and try again; if it keeps failing, contact support with the agent id. Test your agent
The call ended because the workspace ran out of credits. A turn could not be charged, so the session ended. Top up; the turns that were charged are on the conversation. Test your agent
Your trial AI allowance is used up. Upgrade to keep using AI. The trial's AI model cost reached $1. Choose a plan under Subscription; speech tools keep working on trial credits until then. Credits, top-ups and rollover
My agent answered outside its hours Working hours record when you intend the agent to be available; they do not stop it answering. Disconnect the channel or bind it to another agent; to have the agent say it is closed, put the hours in its instructions. Working hours
The agent never calls the tool The tool is not selected on this agent, or its Description does not name the situations it is for. Select it on the agent, then rewrite the Description and each parameter's Description. Webhook tools
The call fails with Tool request failed or timed out Your endpoint did not answer inside the timeout, or the connection failed. Raise Timeout [ms] and confirm the host resolves publicly over HTTPS. Webhook tools
Could not connect the database. An empty Description, a database that could not be reached, a failed TLS handshake, or a connection string that could not be read. Fill in the description, check the host and TLS, then submit again. Connect a database
The connection is Ready but the agent never uses it No question is approved, or the connection is not attached to the agent you are testing. Approve at least one question and attach the connection to the agent. Connect a database

Channels

Symptom Likely cause What to do Page
The agent never replies on WhatsApp The number's access has expired, the workspace has no credits, or the message was not text. Check the row for Token expired. Reconnect. and reconnect it by importing the number again; otherwise top up, or send a text message. Connect WhatsApp
The reply is on the conversation but the customer did not get it WhatsApp refused the reply: most often the number's access has expired (the row reads Token expired. Reconnect.), or Meta revoked access outside EchoNova, for example the number was removed from WhatsApp Manager. If the row reads Token expired. Reconnect., press Import another account and tick the same number again; otherwise disconnect and reconnect the channel. WhatsApp limits
The number is already on another agent Connecting it again from this agent ends with Move this channel?. Confirm Move, which closes its open conversations, or use Assign to another agent on the other agent's Channels tab. Connect WhatsApp
The agent stays quiet in a Slack channel The message does not mention the app, the channel is not the one saved under Edit triggers, the app is not in the channel, or the workspace has no credits. Mention the app with text after it, check the triggers, invite the app to a private channel, and top up. Slack
The agent stays quiet in Slack direct messages Direct Messages is off for this connection. Open the row's menu, choose Edit triggers, tick Direct Messages and press Confirm Connect. Slack
The agent never answers a Messenger message The row is on no agent, the message has no text, the workspace has no credits, or the Page sent the message itself. Check each in that order. Messenger
The caller hears Sorry, this number is not available right now. Goodbye. The workspace has no credits. Top up, then call again; nothing needs to be reconnected. Voice with Twilio
Calls stopped working after the Auth Token was changed in Twilio Every call is checked against the Auth Token saved at connect time. Disconnect the number and connect it again with the new token. Voice with Twilio
The agent does not answer a Zendesk ticket The ticket carries echonova_escalated, the latest public comment is not the requester's, the webhook or triggers were deleted in Zendesk, or the workspace has no credits. Remove the tag to hand the ticket back, reconnect the channel if the webhook or triggers are gone, and top up. Zendesk
Pause Channel does nothing Pause Channel on the channel's detail page does not stop the channel today. Disconnect the channel or assign it to another agent. Slack

API

Symptom Likely cause What to do Page
401 Unauthorized The Authorization header is missing or does not use Bearer, the token does not start with ek_, or the key was deleted or disabled. Check the header, then the key's Status in the portal. Get an API key
403 This API key does not have access to Text-to-Speech services The key restricts Access and the service you called is not among its services; the same message exists for Speech-to-Text. Edit the key and grant Access to the service, or use a different key. Get an API key
429 Monthly spending limit exhausted A Text to Speech call would take the key past its credit limit for this billing cycle. Raise the limit under Edit, clear it for no limit, or wait for the next cycle. Get an API key
402 Insufficient subscription balance The workspace balance cannot cover the charge; nothing was generated. Add credits to the workspace. Text to Speech quickstart
400 Unsupported file type: application/octet-stream. Please upload an audio file. The file part was sent without an audio/ content type; the type in the message is what your client sent. Set the part's type, for example audio/wav. Speech to Text quickstart
400 Audio exceeds the 10-minute limit. The file is longer than 10 minutes. Split the recording into parts of 10 minutes or less. Speech to Text quickstart
429 ThrottlerException: Too Many Requests while polling The poll loop is too tight, or several workers poll with the same key. Wait Retry-After seconds, then raise the poll interval or split the workers across keys. Retry requests safely
The same text produced two jobs and two charges Your client sent the POST twice: a retry layer, automatic retries on POST, or a worker restarted mid-request. Turn off automatic retries for POST; both jobs are real, and the second charge is refunded only if that job fails. Retry requests safely
The webhook switched to Disabled on its own 5 deliveries in a row failed after all retries. Make the endpoint return a 2xx status within 10 seconds, then enable the webhook again. Configure a webhook
The signature never matches The body was re-serialised before hashing, the <timestamp>. prefix was left off, the 12-character prefix was used instead of the full secret, or the secret belongs to another webhook. Log the raw bytes and the timestamp you hashed, and compare their lengths with what arrived. Verify a webhook signature

Worked example

You click Generate on Text to Speech and the page shows Error: Insufficient subscription balance. Find the row under Text to Speech: the cause is a balance that cannot cover the charge, and nothing was charged. Open Subscription from the user menu, add credits with Add More Credits, return to Text to Speech and click Generate again. If the message is one this page does not list, open Generate speech and read its full Troubleshooting section.

FAQ

My message is not on this page. Where is it?

On the page of the feature that showed it. Every page under Playground, Agents, Developers and Account ends with a Troubleshooting section that lists each message the feature can show. Open that page and search it with your browser's find. If it is not there either, write to us as described on Contact and support, with the exact text.

Was I charged when I saw an error?

A speech job that is refused before it runs is not charged, and one that fails after it started is refunded; the full entry on each page says which. Agent turns that were answered before a conversation ended stay charged. Track your credit usage shows every charge and refund.

Why does the API say 402 and the portal say Insufficient subscription balance?

They are the same condition. The portal shows the message text; the API returns the status with the same text in errorMessage. Every API status and message is on Errors.

The fix says to top up. Where is that?

Subscription in the user menu, then Add credits. Which credits a top-up adds and the order they are spent in are on Credits, top-ups and rollover.