Errors & Troubleshooting
Every error code, why it happens, and what to do about it
The SDK reports every failure as a Voice213Error with a code. The realtime protocol uses the same codes. Find yours below, then the fixes for problems that don't raise an error at all.
Error codes
| Code | What happened | What to do |
|---|---|---|
MIC_DENIED | The visitor refused the microphone, or the browser blocks it on this page | Show them how to allow it (the lock icon in the address bar). In an <iframe>, add allow="microphone". |
MIC_UNAVAILABLE | No microphone was found, or another app is using it | Ask them to plug in or free their microphone. setInputDevice() switches to another. |
UNSUPPORTED | The browser can't record audio here. Usually the page isn't HTTPS. | Serve the page over HTTPS (localhost works for development). Suggest a current Chrome, Edge, Firefox or Safari. |
AUDIO | The audio processor couldn't load | Your Content-Security-Policy blocks blob: scripts. Serve @voice213/agent-client/worklet.js yourself and pass audio: { workletUrl }. |
NOT_FOUND | No live agent has this id | Check the public id on Publish, that the agent is live, and that Enable link and widget is on. |
ORIGIN | This website isn't in the agent's Allowed websites | Add the exact origin: https://www.myshop.dz and https://myshop.dz are two different sites. In development, add http://localhost:3000. |
RATE_LIMITED | This visitor's IP address started 20 calls in the last hour | It lifts within the hour. |
QUOTA | The agent's account has no call minutes left, or under 30 seconds | Top up or upgrade the agent plan. |
BUSY | The account already has 5 calls running, or every line is busy | Retry in a minute. |
MODEL | No voice model could be reached | Retry. Voice213 already tried every model before giving up. |
TICKET | Voice213 refused the call for another reason (status has the HTTP code) | Read message. Retry later, or contact support with it. |
ERROR | The call failed for an unexpected reason | Retry. If it keeps happening, contact support with the time and the agent's public id. |
UNAVAILABLE | Voice213 is down for maintenance | Retry later. |
OWNER | The agent's account no longer exists | |
NETWORK | Voice213 couldn't be reached, or refused the call ticket | Check the connection. A corporate firewall or proxy may block WebSockets to api.voice213.com. |
CLOSED | The connection closed before the call started | Retry. |
TIMEOUT | The agent didn't pick up within connectTimeoutMs (50 s) | Retry. Check the visitor's connection. |
CANCELLED | end() was called before the call connected | Nothing to fix: you cancelled it. |
STATE | start() was called while a call is already running | Call end() first, or check status. |
The message of each error is written for people, in English. Show your own text to visitors, chosen from the code.
The agent hears itself and keeps stopping
On laptop speakers, the agent's voice reaches the microphone. The SDK guards against it in two ways. In Chrome and Edge, it plays the agent through WebRTC so the browser's echo cancellation can remove it. Everywhere, the echo gate sends quiet sound as silence while the agent speaks. If the agent still cuts itself off:
- keep
echoCancellationon (the default); - raise
echoGate, for example to0.04, in a loud room or on a device with strong speakers; - lower the agent's interruption sensitivity to Low;
- suggest headphones for long calls.
The agent cuts the caller off, or answers slowly
That's response speed: how long the caller must pause before the agent answers. Choose Calm for callers who pause mid-sentence, Fast for quick exchanges, or set the exact silence under Fine timing. See Voice & Behavior.
The agent spoke another language
Each agent speaks exactly one language and is locked to it. See Languages & Dialects. If you still hear it switch:
- check the language in Setup → Identity → Language & dialect: an agent that was on "Match the caller" now speaks Algerian Darija;
- check the first message: a fixed message is said word for word, so write it in the agent's language;
- look for instructions that tell it to switch ("answer in French if the customer speaks French"), and remove them;
- to serve two languages, create two agents.
No sound
- On iPhone and iPad, sound only starts from a tap. Call
start()directly in the click or tap handler, not after anawaitor a timer. - The device may be on silent, or its volume low.
- Something else on the page may have taken the audio output.
setOutputDevice()picks a speaker on Chrome and Edge.
The agent makes things up, or doesn't know something
It answers only from its knowledge base, so add the missing fact. Use Test the knowledge on the Knowledge base page to see what it finds for a question. See Knowledge Base.
A tool doesn't run, or fails
- It never runs: the agent decides from the tool's description. Make it say when to use it, and mention the tool in the instructions ("when the customer confirms, call
confirm_order"). - It fails: Test on the Tools page runs it for real and shows your server's answer. Your endpoint must be public. Private and local addresses are refused, and the timeout is 15 seconds by default.
- In test chats it does nothing: tools are simulated there unless Run tools for real is on.
See Tools.
A webhook fails
Its card on Webhooks shows the last delivery's status and error. Use Send test to try again. Answer within 10 seconds with a 2xx, and verify the signature against the raw body. See Webhooks.
Still stuck?
Message us on WhatsApp at +213 672 00 84 26 or email support@voice213.com. Send the agent's public id, the conversationId of the call if it connected, and the error code.
Was this page helpful?