Diagnose and fix Retell AI common errors and exceptions. Use when encountering Retell AI errors, debugging failed requests, or troubleshooting integration issues. Trigger with phrases like "retellai error", "fix retellai", "retellai not working", "debug retellai".
npxskills add jeremylongshore/claude-code-plugins-plus-skills--skill retellai-common-errorsLoading…
Quick reference for the top Retell AI errors and their solutions.
retell-sdk installedRetellError: 401 — Invalid API key
Fix: Verify API key in Retell Dashboard. Ensure RETELL_API_KEY starts with key_.
RetellError: 400 — Invalid phone number format
Fix: Use E.164 format: +14155551234. Both from_number and to_number must be valid.
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
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.body.args);
res.json({ result: `Found: ${result.name}` });
// Do NOT run async work before responding
});
No webhook events received after call
Fix: Set webhook_url on the agent, not just in Dashboard settings:
await retell.agent.update(agentId, {
webhook_url: 'https://your-app.com/webhooks/retell',
});
Agent voice sounds robotic/choppy
Fix: Check network latency to Retell servers. Use a voice optimized for your use case. Try different voice IDs.
| HTTP Code | Meaning | Retryable |
|---|---|---|
| 400 | Bad request | No — fix params |
| 401 | Invalid API key | No — fix key |
| 404 | Agent/call not found | No — fix ID |
| 429 | Rate limited | Yes — backoff |
| 500+ | Server error | Yes — retry |
For debugging, see retellai-debug-bundle.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).