About

Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/retellai-common-errors/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill retellai-common-errors. Copyright stays with the author (MIT).

Retell AI Common Errors

Name: retellai-common-errors
Author: jeremylongshore

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

Next Steps

For debugging, see retellai-debug-bundle.

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/jeremylongshore-tons-of-skills-marketplace-retellai-comm-fc6da9/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

jeremylongshore-tons-of-skills-marketplace-retellai-comm-fc6da9.ocm.jsonjson

{
  "ocm": "1",
  "id": "jeremylongshore-tons-of-skills-marketplace-retellai-comm-fc6da9",
  "kind": "skill",
  "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\".",
  "publisher": "jeremylongshore",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "coding",
      "customer_support"
    ],
    "tags": [
      "skill-md",
      "saas",
      "retellai",
      "voice",
      "telephony",
      "debugging",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "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\"."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/jeremylongshore/tons-of-skills-marketplace",
      "path": "skills/.curated/retellai-common-errors/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/jeremylongshore/tons-of-skills-marketplace/blob/HEAD/skills/.curated/retellai-common-errors/SKILL.md",
      "key": "jeremylongshore/tons-of-skills-marketplace/skills/.curated/retellai-common-errors/SKILL.md"
    },
    "compatibility": "Designed for Claude Code",
    "allowed_tools": [
      "Read,",
      "Grep,",
      "Bash(curl:*)"
    ],
    "license": "MIT"
  },
  "instructions": "# Retell AI Common Errors\n\n## Overview\n\nQuick reference for the top Retell AI errors and their solutions.\n\n## Prerequisites\n\n- `retell-sdk` installed\n- API key configured\n\n## Instructions\n\n### Error 1: 401 Unauthorized\n\n```\nRetellError: 401 — Invalid API key\n```\n\n**Fix:** Verify API key in Retell Dashboard. Ensure `RETELL_API_KEY` starts with `key_`.\n\n### Error 2: Call Fails Immediately\n\n```\nRetellError: 400 — Invalid phone number format\n```\n\n**Fix:** Use E.164 format: `+14155551234`. Both `from_number` and `to_number` must be valid.\n\n### Error 3: Agent Not Responding\n\n```\nCall connected but a",
  "cost": {
    "context_tokens": 738
  }
}

Fetch it by URL: GET /api/v1/registry/jeremylongshore-tons-of-skills-marketplace-retellai-comm-fc6da9/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.