> For the full page index, fetch https://echonova.ai/llms.txt # 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. > [!NOTE] > 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](/docs/account/sign-in-methods#the-email-username-or-password-is-not-correct) | | **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](/docs/account/sign-in-methods#verify-your-email-first-enter-the-code-we-sent-you) | | **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](/docs/account/sign-in-methods#that-code-is-not-correct-check-it-and-try-again) | | **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](/docs/account/sign-in-methods#that-code-has-expired-request-a-new-one) | | **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](/docs/get-started/sign-up-and-create-a-workspace#an-account-with-this-email-already-exists) | | **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](/docs/account/two-factor-authentication#that-code-is-not-correct-check-it-and-try-again) | | **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](/docs/account/two-factor-authentication#something-went-wrong-please-try-again) | ## 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](/docs/account/plans-and-subscription#could-not-start-checkout) | | **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](/docs/account/plans-and-subscription#subscription-is-canceled-but-still-active-until-period-ends-use-reactivate-instead) | | **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](/docs/account/plans-and-subscription#you-lack-the-required-permission-s-billing-manage) | | **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](/docs/account/payment-methods#payment-failed) | | **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](/docs/help/contact-and-support) with the time of the payment. | [Pay and manage your payment method](/docs/account/payment-methods#confirmation-failed) | | **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](/docs/account/payment-methods#could-not-confirm-your-credit-purchase) | | **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](/docs/account/usage#balance-after-does-not-match-the-sidebar) | ## 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](/docs/playground/generate-speech#the-generate-button-is-greyed-out) | | **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](/docs/playground/generate-speech#error-insufficient-subscription-balance) | | **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](/docs/playground/generate-speech#error-speech-generation-is-temporarily-unavailable-please-try-again) | | **Error: Voice not found** | The selected voice has been withdrawn. | Click **Change voice** and pick another one. | [Generate speech](/docs/playground/generate-speech#error-voice-not-found) | | **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](/docs/playground/generate-speech#error-text-must-be-shorter-than-or-equal-to-5000-characters) | | 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](/docs/playground/add-diacritics#the-tashkeel-switch-is-not-there) | | 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](/docs/playground/add-diacritics#nothing-changed-after-i-turned-it-on) | | 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](/docs/get-started/quickstart-first-speech#the-audio-plays-but-download-gives-me-a-file-i-cannot-open) | ## 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](/docs/playground/transcribe-a-file#please-upload-one-of-mp3-wav-flac-ogg-m4a-aac-webm) | | **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](/docs/playground/transcribe-a-file#audio-must-be-1-hour-or-shorter) | | **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](/docs/playground/transcribe-a-file#transcription-is-temporarily-unavailable-please-try-again) | | **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](/docs/playground/transcribe-a-file#job-timed-out-ai-server-did-not-respond) | | 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](/docs/playground/reading-results#the-card-reads-no-speech-was-found-in-this-file) | | **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](/docs/playground/clean-a-recording#that-clip-is-longer-than-1-hour-split-it-and-try-again) | | **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](/docs/playground/clean-a-recording#sound-cleaning-is-temporarily-unavailable-please-try-again) | | **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](/docs/playground/clean-a-recording#cleaning-stopped-before-it-finished-try-again) | ## 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](/docs/agents/create-an-agent#plan-limit-reached) | | **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](/docs/agents/persona#this-agent-is-archived-restore-it-first-to-make-changes) | | **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](/docs/agents/model-and-reasoning#this-model-is-no-longer-available-pick-another-to-keep-this-agent-working) | | **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](/docs/agents/knowledge-documents#storage-limit-exceeded-for-this-workspace-delete-files-or-upgrade-your-plan) | | 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](/docs/agents/knowledge-documents#the-row-says-failed) | | 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](/docs/agents/knowledge-troubleshooting#everything-is-ready-and-selected-but-the-agent-still-misses-it) | | 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](/docs/agents/knowledge-troubleshooting#the-agent-invents-an-answer-instead-of-saying-it-does-not-know) | | **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](/docs/agents/test-your-agent#no-reply-try-again) | | **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](/docs/help/contact-and-support) with the agent id. | [Test your agent](/docs/agents/test-your-agent#could-not-start-the-voice-session) | | **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](/docs/agents/test-your-agent#the-call-ended-because-the-workspace-ran-out-of-credits) | | **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](/docs/account/credits-top-ups-rollover#trial-credits) | | 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](/docs/agents/working-hours#my-agent-answered-outside-its-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](/docs/agents/webhook-tools#the-agent-never-calls-the-tool) | | 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](/docs/agents/webhook-tools#the-call-fails-with-tool-request-failed-or-timed-out) | | **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](/docs/agents/database-tools-connect#could-not-connect-the-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](/docs/agents/database-tools-connect#the-connection-is-ready-but-the-agent-never-uses-it) | ## 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](/docs/agents/whatsapp-connect#the-agent-never-replies) | | 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](/docs/agents/whatsapp-limits#replies-the-agent-sends) | | 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](/docs/agents/whatsapp-connect#the-number-is-already-on-another-agent) | | 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](/docs/agents/slack#the-agent-stays-quiet-in-the-channel) | | 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](/docs/agents/slack#the-agent-stays-quiet-in-direct-messages) | | 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](/docs/agents/messenger#the-agent-never-answers-a-message) | | 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](/docs/agents/voice-twilio#the-caller-hears-sorry-this-number-is-not-available-right-now-goodbye) | | 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](/docs/agents/voice-twilio#calls-stopped-working-after-i-changed-the-auth-token-in-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](/docs/agents/zendesk#the-agent-does-not-answer-a-ticket) | | **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](/docs/agents/slack#pause-channel-does-nothing) | ## 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](/docs/developers/get-an-api-key#401-unauthorized) | | **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](/docs/developers/get-an-api-key#403-this-api-key-does-not-have-access-to-text-to-speech-services) | | **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](/docs/developers/get-an-api-key#429-monthly-spending-limit-exhausted) | | **402 Insufficient subscription balance** | The workspace balance cannot cover the charge; nothing was generated. | Add credits to the workspace. | [Text to Speech quickstart](/docs/developers/tts-quickstart#402-insufficient-subscription-balance) | | **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](/docs/developers/stt-quickstart#400-unsupported-file-type-application-octet-stream-please-upload-an-audio-file) | | **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](/docs/developers/stt-quickstart#400-audio-exceeds-the-10-minute-limit) | | **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](/docs/developers/retries-and-idempotency#429-throttlerexception-too-many-requests-while-polling) | | 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](/docs/developers/retries-and-idempotency#the-same-text-produced-two-jobs-and-two-charges) | | 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](/docs/developers/webhooks-configure#the-webhook-switched-to-disabled-on-its-own) | | The signature never matches | The body was re-serialised before hashing, the `.` 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](/docs/developers/webhooks-verify-signature#the-signature-never-matches) | ## 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](/docs/playground/generate-speech#troubleshooting) 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](/docs/help/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](/docs/account/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](/docs/developers/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](/docs/account/credits-top-ups-rollover). ## Related - [Contact and support](/docs/help/contact-and-support): where to write when the fix on this page does not work - [Glossary](/docs/help/glossary): the words the tables above use - [Errors](/docs/developers/errors): every status and message the API returns - [The agent did not use my document](/docs/agents/knowledge-troubleshooting): the five checks for a knowledge source that never reaches a turn - [Track your credit usage](/docs/account/usage): whether a job was charged or refunded