retellai-common-errors

name	retellai-common-errors
description	Diagnose and fix Retell AI voice agent errors: call failures, webhook issues, voice quality. Use when encountering Retell AI errors, debugging call issues, or troubleshooting agents. Trigger with phrases like "retell error", "call failed", "voice agent not working", "retell debug".
allowed-tools	Read, Grep, Bash(curl:*)
version	1.9.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","retellai","voice","telephony","debugging"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

Retell AI Common Errors

Overview

Quick reference for the top Retell AI errors and their solutions.

Prerequisites

• retell-sdk installed
• API key configured

Instructions

Error 1: 401 Unauthorized

RetellError: 401 — Invalid API key

Fix: Verify API key in Retell Dashboard. Ensure RETELL_API_KEY starts with key_.

Error 2: Call Fails Immediately

RetellError: 400 — Invalid phone number format

Fix: Use E.164 format: [phone]. Both from_number and to_number must be valid.

Error 3: Agent Not Responding

Call connected but agent says nothing

Fix: Check LLM configuration:

const llm = await retell.llm.retrieve(agent.response_engine.llm_id);
console.log(`Model: ${llm.model}`);
console.log(`Prompt length: ${llm.general_prompt.length} chars`);
// Ensure general_prompt is not empty and gives clear instructions

Error 4: Function Call Timeout

Function call to https://your-api.com/endpoint timed out

Fix: Your function endpoint must respond within 5 seconds. Offload heavy work:

app.post('/functions/lookup', async (req, res) => {
  // Respond immediately with acknowledgment
  const result = await quickLookup(req..);
  res.({ :  });
  
});