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.

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.
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.
concurrency_limit_reachedError, concurrency limit reached, add a retry with exponential backoff. Or consider enterprise plan.
dial_busyThe number dialed in busy.
dial_failedDailing failed, usually due to number is non existent.
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.

​
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: current concurrency limit for pay-as-you-go plan is 10 calls. You can check if you have excessive amount of ongoing calls with List Calls API.

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