---
name: retellai-known-pitfalls
description: "Retell AI known pitfalls \u2014 AI voice agent and phone call automation.\n\
Use when working with Retell AI for voice agents, phone calls, or telephony.\nTrigger\
\ with phrases like \"retell known pitfalls\", \"retellai-known-pitfalls\", \"voice\
\ agent\".\n"
allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(curl:*), Grep
version: 1.9.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
- saas
- retellai
- voice
- telephony
- ai-agents
compatibility: Designed for Claude Code
---
# Retell AI Known Pitfalls
## Overview
Implementation patterns for Retell AI known pitfalls — voice agent and telephony platform.
## Prerequisites
- Completed `retellai-install-auth` setup
## Instructions
### Step 1: SDK Pattern
```typescript
import Retell from 'retell-sdk';
const retell = new Retell({ apiKey: process.env.RETELL_API_KEY! });
const agents = await retell.agent.list();
console.log(`Agents: ${agents.length}`);
```
## Output
- Retell AI integration for known pitfalls
## Error Handling
| Error | Cause | Solution |
|-------|-------|----------|
| 401 Unauthorized | Invalid API key | Check RETELL_API_KEY |
| 429 Rate Limited | Too many requests | Implement backoff |
| 400 Bad Request | Invalid parameters | Check API documentation |
## Examples
### Avoid a duplicate-call retry after a network timeout
An outbound request times out after submission. Before retrying, look up the
request correlation or call identifier to determine whether Retell already
created the call. If state is unknown, hold the retry and escalate with the
redacted request metadata; sending a second request can contact the same
person twice. Add bounded retries only where the operation is explicitly
idempotent and monitor the duplicate-call rate after the change.
## Resources
- [Retell AI Documentation](https://docs.retellai.com)
- [retell-sdk npm](https://www.npmjs.com/package/retell-sdk)
## Next Steps
See related Retell AI skills for more workflows.
