> ## Documentation Index
> Fetch the complete documentation index at: https://plivo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Call Failures

> Debug and resolve voice call issues including failed connections, one-way audio, and quality problems

Use this guide to diagnose and fix common voice call issues. Start with the symptom you're experiencing.

***

## Quick Diagnosis

> [accordion] Outbound calls not connecting
>
> **Check in order:**
>
> 1. Verify credits balance in Console → Billing
> 2. Check geo permissions for destination country
> 3. Verify caller ID is a Plivo number or verified
> 4. Review [hangup cause](https://plivo.com/docs/voice/troubleshooting/hangup-causes.md) in call logs
>
> **Common causes:**
>
> | Hangup Cause | Solution |
> | - | - |
> | `destination_country_barred` | Enable country in Console → Voice → Geo Permissions |
> | `unknown_caller_id` | Use Plivo-rented number as caller ID |
> | `insufficient_credits` | Add credits to account |
> | `invalid_destination` | Use E.164 format (+14155551234) |

> [accordion] Inbound calls not reaching my app
>
> **Check in order:**
>
> 1. Verify number is assigned to an application (Console → Phone Numbers)
> 2. Check application Answer URL is accessible
> 3. Verify Answer URL returns valid Plivo XML
> 4. Check for firewall blocking Plivo IPs
>
> **Debug steps:**
>
> 1. Go to Console → Voice → Logs → Calls
> 2. Find the failed call
> 3. Check the hangup cause and debug logs
> 4. Test your Answer URL manually with curl

> [accordion] Calls connect but no audio (one-way or silent)
>
> **Common causes:**
>
> * Firewall blocking RTP/media ports
> * NAT traversal issues
> * Codec mismatch
>
> **Solutions:**
>
> 1. Whitelist Plivo IP ranges for UDP ports 10000-60000
> 2. Enable STUN/TURN if behind NAT
> 3. Use standard codecs (G.711, Opus)
>
> See [Plivo IP Ranges](https://www.plivo.com/docs/voice/concepts/ip-addresses/) for whitelisting.

> [accordion] Calls dropping mid-conversation
>
> **Check hangup cause in call logs:**
>
> | Hangup Cause | Meaning | Solution |
> | - | - | - |
> | `scheduled_hangup` | Max duration reached | Increase `time_limit` parameter |
> | `media_timeout` | No audio for 60 seconds | Check network stability |
> | `xml_end` | No more XML instructions | Add more XML or use `<Wait>` |
> | `insufficient_credits` | Ran out of credits mid-call | Enable auto-recharge |

> [accordion] Poor audio quality (echo, delay, choppy)
>
> | Issue | Likely Cause | Solution |
> | - | - | - |
> | Echo | Acoustic feedback | Use headset, reduce speaker volume |
> | Delay/latency | Network distance | Use nearest Plivo region |
> | Choppy audio | Packet loss | Check internet connection, reduce bandwidth usage |
> | Robotic voice | Codec issues | Use G.711 codec |
>
> For persistent issues, capture a PCAP and contact [Plivo Support](https://support.plivo.com).

***

## Step-by-Step Debugging

### 1. Check Call Logs

1. Go to **Console → Voice → Logs → Calls**
2. Find the failed call by time or phone number
3. Note the **Hangup Cause** and **Hangup Source**
4. Click the call to view debug details

### 2. Verify Configuration

**For outbound calls:**

```bash theme={null}
# Test your setup with curl
curl -i --user AUTH_ID:AUTH_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"from": "+14155551234", "to": "+14155559876", "answer_url": "https://example.com/answer"}' \
  https://api.plivo.com/v1/Account/{auth_id}/Call/
```

**For inbound calls:**

* Verify number → application assignment in Console
* Test Answer URL returns valid XML

### 3. Test Answer URL

Your Answer URL must:

* Return HTTP 200 status
* Return `Content-Type: application/xml` or `text/xml`
* Return valid [Plivo XML](https://plivo.com/docs/voice/xml/overview.md)

**Example valid response:**

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Speak>Hello, this is a test call.</Speak>
</Response>
```

### 4. Check Firewall Settings

Plivo requires these ports open:

| Traffic | Protocol | Ports |
| - | - | - |
| SIP signaling | UDP/TCP | 5060, 5080 |
| Secure SIP | TLS | 5061 |
| RTP (audio) | UDP | 10000-60000 |
| HTTPS callbacks | TCP | 443 |

See [IP Addresses](https://plivo.com/docs/voice/concepts/firewall-network-configuration.md) for ranges to whitelist.

***

## Common Error Scenarios

### "Call immediately goes to voicemail"

**Possible causes:**

1. Carrier is blocking based on caller ID reputation
2. Number flagged as spam
3. Destination has call blocking enabled

**Solutions:**

* Register for STIR/SHAKEN attestation
* Use a different caller ID
* Contact carrier about spam flagging

### "API returns 403 Forbidden"

**Check:**

1. Account is verified and active
2. Geo permissions enabled for destination
3. Caller ID is verified or Plivo-owned
4. No outstanding balance issues

### "Calls work sometimes but not always"

**Debug steps:**

1. Check if failures correlate with specific destinations
2. Review call volume vs CPS limits
3. Check for carrier-specific issues in logs
4. Monitor for pattern (time of day, destination, etc.)

***

## Debug Logs

For detailed debugging, enable debug logs:

1. Go to **Console → Voice → Logs → Calls**
2. Click on the specific call
3. View the **Debug** tab for:
   * XML requests/responses
   * SIP signaling details
   * Timing information

***

## When to Contact Support

Contact [Plivo Support](https://support.plivo.com) if:

* Issue persists after following this guide
* You see `internal_error` or `routing_error` hangup causes
* Calls fail with no clear hangup cause
* You need PCAP analysis for audio issues

**Include in your support request:**

* Call UUID(s)
* Timestamp of failures
* Steps already tried
* Any error messages

***

## Related

* [Hangup Causes Reference](https://plivo.com/docs/voice/troubleshooting/hangup-causes.md)
* [Voice API Overview](https://plivo.com/docs/voice/api/overview.md)
* [IP Addresses](https://plivo.com/docs/voice/concepts/firewall-network-configuration.md)
* [Account Limits](https://plivo.com/docs/voice/concepts/account-limits.md)