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 <jeremy@intentsolutions.io>
tags:
- saas
- retellai
- voice
- telephony
- debugging
compatibility: Designed for Claude Code
---
# 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:

```typescript
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:

```typescript
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:

```typescript
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](https://docs.retellai.com)
- [retell-sdk npm](https://www.npmjs.com/package/retell-sdk)

## Next Steps

For debugging, see `retellai-debug-bundle`.