# Retellai Known Pitfalls

> Retell AI known pitfalls — AI voice agent and phone call automation. Use when working with Retell AI for voice agents, phone calls, or telephony. Trigger with phrases like "retell known pitfalls", "retellai-known-pitfalls", "voice agent".

- Skill: `gabrielmoreira/retellai-known-pitfalls` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add gabrielmoreira/retellai-known-pitfalls`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/retellai-known-pitfalls/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/gabrielmoreira/retellai-known-pitfalls

---

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