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

Examples

Triage a failed outbound call request

When an outbound request returns an error, record the HTTP status, request correlation ID, and the target environment without storing the phone number in the shared incident log. Retry only idempotent requests with bounded backoff; do not retry an ambiguous call-creation response until the provider state is checked. If the error is credential-related, rotate the affected test secret and confirm the replacement against a sandbox agent before resuming traffic.

Resources

• Retell AI Documentation
• retell-sdk npm

Next Steps

For debugging, see retellai-debug-bundle.