Troubleshoot call errors
Overview
When a call fails, the fastest path to a fix is identifying what the caller experienced. This guide organizes errors by symptom so you can jump to the right section and resolve the issue.
In this guide, you’ll learn to:
- Match caller-reported symptoms to specific error codes
- Understand the fault classification system (
vapifaultvsproviderfault) - Take the right corrective action for each error category
This guide explains errors by symptom. For a complete reference of every endedReason code, see Call end reasons.
Start here: identify the symptom
Call failed immediately — no ring on the customer’s end
Phone rang but was never picked up, or line was busy
Caller was talking, then the line went dead abruptly
Call connected but the assistant stopped speaking or responding
Assistant attempted a transfer but it didn’t go through
Call worked as expected — someone or something decided it should end
Phone never rang
What the caller experiences: Nothing. The phone never rings. For web calls, the connection fails immediately.
What you see in the dashboard: The call object is created with status ended almost immediately. Duration is zero or near-zero. No transcript.
Account and billing errors
These are the most common cause of calls failing before they start.
Configuration errors
The call couldn’t start because something is missing or misconfigured.
Server URL errors
If you use a server URL to dynamically provide an assistant, these errors mean your server didn’t respond correctly.
Infrastructure errors
These indicate a problem on Vapi’s side. You are typically not charged.
Phone rang but nobody answered
What the caller experiences: The phone rings but nobody picks up, or they hear a busy signal.
What you see in the dashboard: Short duration, no transcript, no messages.
For outbound calls where you expect to reach an IVR or automated system, configure your voicemail detection settings to prevent the call from ending prematurely.
Call dropped mid-conversation
What the caller experiences: They’re in the middle of a conversation and the call suddenly cuts off with no warning. The assistant stops speaking and the line goes dead.
What you see in the dashboard: Partial transcript, messages array that ends abruptly, non-zero duration.
Vapi infrastructure issues (vapifault)
These are on Vapi’s side. You are typically not charged. Most are transient.
What to do: These are transient issues. If worker-died errors are frequent, contact support with the affected call_id values.
Telephony provider disconnects
The telephony provider (Twilio, Vonage, or your SIP trunk) dropped the connection.
What to do: Check your telephony provider’s dashboard for connection logs. For SIP trunks, verify your network connectivity to Vapi’s SBC.
Assistant went silent or unresponsive
What the caller experiences: The call is connected and the line is open, but the assistant either doesn’t speak, speaks with extreme delay, responds once then stops, or produces garbled audio. The call eventually times out or the caller hangs up in frustration.
What you see in the dashboard: Partial messages, the endedReason points to a specific pipeline component failure.
If you’ve configured fallback providers, some transcriber and voice errors will trigger a provider swap instead of ending the call. The caller might hear a brief 1-2 second pause while the fallback initializes, then the conversation continues normally.
LLM / model errors
The AI model that generates responses is unreachable or returning errors.
Voice / TTS errors
The text-to-speech service can’t produce audio. The assistant “thinks” but can’t speak.
Transcriber / STT errors
The speech-to-text service can’t hear the caller. The assistant can speak but can’t understand input.
To prevent provider outages from killing your calls, configure fallback providers for your transcriber, voice, and model. Non-fatal errors will trigger a provider swap instead of ending the call.
Transfer failed
What the caller experiences: The assistant says it’s transferring the call, but the transfer doesn’t go through. The caller may hear silence, get disconnected, or return to the original assistant (for warm transfers).
What you see in the dashboard: Transcript shows the transfer attempt, followed by the error.
General transfer errors
SIP transfer errors
Telephony provider transfer errors
For a detailed transfer debugging walkthrough, see Debug forwarding drops.
Call ended normally
These are not errors — they indicate the call ended as expected.
Next steps
- Call end reasons: Complete reference of every
endedReasoncode. - Debugging voice agents: General debugging workflow using dashboard tools, logs, and test suites.
- Debug forwarding drops: Deep dive into transfer failures.
- Troubleshoot SIP trunk errors: Resolve SIP credential validation failures.
- How to report issues: Include your
call_idand account email when contacting support.
