---

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

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
• retell-sdk npm

Next Steps

See related Retell AI skills for more workflows.