During the development of your Retell agents, you may encounter issues that prevent your agents from working as expected. Sometimes it’s telecommunication, sometimes it’s the prompts need improvement, sometimes it’s connection issue. This guide will provide you with useful tips to locate and address these issues.

This guide assume you have already setup your agent and have a basic understanding of how to use Retell.

Check Retell Server Status Page to monitor if it’s a Retell issue.

​
Disconnection Reason

Find the Disconnection Reason through Dashboard or get-call.

Please note that when phone numbers enagage in a lot of short calls in a short period, it might be marked as spam at carrier level, which in turn leads to number being blocked and show up as dial_failed.
Disconnection ReasonDescription
user_hangupExpected behavior, user hangup the call.
agent_hangupExpected behavior, AI agent hangup the call.
call_transferExpected behavior, AI agent transferred the call.
voicemail_reachedExpected behavior, if AI agent configured voicemail settings, and reached voicemail.
inactivityExpected behavior, call was terminated due to the “end_call_after_silence_ms” setting reached after long inactivity.
machine_detectedExpected behavior, call was terminated due to the “drop_call_if_machine_detected” setting triggering when an voicemail or similar is detected.
max_duration_reachedExpected behavior, call was terminated due to maximum duration reached.
concurrency_limit_reachedError, concurrency limit reached, add a retry with exponential backoff. Or consider enterprise plan.
no_valid_paymentError, no valid payment registered on file, or service shut down due to bill overdue.
scam_detectedError, scam detected for that particular agent.
error_inbound_webhookError, failed to retrieve dynamic variables for inbound phone call.
dial_busyThe number dialed in busy.
dial_failedDailing failed, might be due to callee number is non existent, or the agent number is marked as spam and got blocked.
dial_no_answerThe number dialed did not answer.
error_llm_websocket_openError, LLM websocket did not open between Retell server and your backend. Likely because the Custom LLM URL is incorrect or your LLM server is not reachable.
error_llm_websocket_lost_connectionError, LLM websocket connection broke during the call.
error_llm_websocket_runtimeError, LLM websocket received a closing signal other than 1000 from your server.
error_llm_websocket_corrupt_payloadError, LLM websocket received unspecified payload.
error_frontend_corrupted_payloadError, frontend audio websocket received unspecified payload.
error_twilioError, Twilio websocket connection between Retell server encountered an error.
error_no_audio_receivedError, has not received audio from Twilio or web frontend for a while after connection has established.
error_asrError, Retell’s ASR encountered a problem.
error_retellError, unspecified Retell side problem.
error_unknownError, unknown error.
error_user_not_joinedError, user did not join web call within 30s after calling startWebCall.
registered_call_timeoutError, phone call is 30s or more apart from registering.

​
Problem: Call is not Connecting

Here are a couple common possible causes for this issue, and you can see a more detailed error message when you are using Dashboard (will show up as a pop up when you click web call button):

  1. You have ran out of credit, and have not added payment account. To check your credit balance, go to the Dashboard and click on the “Billing” tab.
  2. You have been rate limited. Check Concurrency Guide for more info.

Apart from these common causes, there are other possible causes for this issue for different scenarios.

​
Phone Call with Custom Twilio

There’re a couple possible causes for this issue:

  1. Check if your Twilio account has enough balance to make the call.
  2. Check if your voice webhook for Twilio is correctly set up. You can add logging to see if that’s being called.
  3. Check if in voice webhook you returned the correct audio websocket url.
  4. Check if your Register Call API is correctly called and returned the correct response.

​
Web Call

There’re a couple possible causes for this issue:

  1. Check if your Register Call API is correctly called and returned the correct response.
  2. Check if your frontend is connecting to the right audio websocket url.

​
Custom LLM

For troubleshooting custom LLM, check Custom LLM Troubleshooting Guide.

​
Problem During the call

This refers to the broad category of issues that occur during the call, such as:

  • call dropped during the call
  • agent not responding
  • function calling not working (for Retell LLM)

To debug, take a look at the public_log_url in Get Call API. This contains all the requests, responses between Retell and LLM, contains the error message if there’s any, and contains all function calling requests sand responses.

To address these issues, you might need to:

  • Prompt engineering
  • Check message format sent in LLM websocket (for custom LLM)

Was this page helpful?

SDKOverview