Retell AI Common Errors Skill

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: +14155551234. 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.body.args);
  res.json({ result: `Found: ${result.name}` });
  // Do NOT run async work before responding
});

Error 5: Webhook Not Receiving Events

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',
});

Error 6: Voice Quality Issues

Agent voice sounds robotic/choppy

Fix: Check network latency to Retell servers. Use a voice optimized for your use case. Try different voice IDs.

Output

Error identified and root cause found
Fix applied and verified
Call successfully completed

Error Handling

| 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 |

Resources

Next Steps

For debugging, see retellai-debug-bundle.

Agent Skills: Retell AI Common Errors

Install this agent skill to your local

Skill Files