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

# Calls fail to connect or drop early

> Diagnose Bolna Voice AI calls that never connect or end too soon, using call statuses, hangup codes, balance and guardrail checks, and silence-based termination settings.

Start from the call's own record. Every execution carries a `status`, and every terminated call carries `hangup_by`, `hangup_code` and `hangup_reason` — those four fields identify the cause faster than any amount of re-testing.

<Steps>
  <Step title="Read the status">
    Open the call in [Call history](/docs/agent-setup/call-history), or fetch it with [`GET /executions/{id}`](/docs/api-reference/executions/get_execution). Match the value against [Call statuses](/docs/post-call/list-phone-call-status).
  </Step>

  <Step title="Read the hangup fields">
    For calls that connected and then ended, `hangup_by` tells you whether the caller, the agent, or the carrier ended it. Look the code up in [Hangup codes](/docs/post-call/list-phone-call-hangup-status).
  </Step>
</Steps>

***

## The call never connects

| Status | What it means | What to do |
| - | - | - |
| `balance-low` | Not enough wallet balance to place the call | Top up. Monitor balance before large batches — see [Handle failures and retries at scale](/docs/production/failures-and-retries-at-scale). |
| `rescheduled` | Triggered outside your allowed calling window | Expected behavior if [calling guardrails](/docs/outbound/calling-guardrails) are on. The window is evaluated in the **recipient's** timezone. |
| `no-answer` / `busy` | The far end did not pick up | Not a fault. Enable [auto-retry](/docs/outbound/auto-retry) rather than re-triggering manually. |
| `failed` / `error` | The call could not be placed | Check `error_message`, then the number format (E.164, with country code) and the telephony provider connection. |
| `stopped` | Stopped by a user, or no response from the telephony provider | If you did not stop it, treat it as a provider-side failure and check the provider's own logs. |

<Info>
  A call scheduled through the API must be at least **two minutes** in the future and use a numeric UTC offset such as `+00:00`. A `Z` suffix is rejected. See [Schedule a batch](/docs/api-reference/batches/schedule).
</Info>

***

## The call connects, then ends too soon

<CardGroup cols={2}>
  <Card title="Silence-based hangup" icon="volume-slash">
    The agent hangs up after a configured period of silence. If callers are being cut off while thinking, raise that limit — see [End a call automatically](/docs/outbound/hangup-calls).
  </Card>

  <Card title="Maximum call duration" icon="clock">
    `call_terminate` caps total call length. Long support calls hitting a short cap look exactly like a drop.
  </Card>

  <Card title="Voicemail detection" icon="voicemail">
    With detection on, a call answered by voicemail is ended deliberately. Check the [Call tab](/docs/agent-setup/call-tab) if legitimate answers are being dropped.
  </Card>

  <Card title="Carrier disconnect" icon="tower-cell">
    `hangup_by` pointing at the carrier, especially in one region, is a routing problem, not an agent problem.
  </Card>
</CardGroup>

***

## When it is only some calls

Pull a batch of executions with [`GET /v2/agent/{agent_id}/executions`](/docs/api-reference/executions/get_executions) and group failures by status, destination country and telephony provider. A failure concentrated in one country or one provider is a telephony issue; a failure spread evenly is a configuration issue.

***

## Next steps

<CardGroup cols={3}>
  <Card title="Call statuses" icon="ballot-check" href="/docs/post-call/list-phone-call-status">
    Every status, explained
  </Card>

  <Card title="Hangup codes" icon="phone-xmark" href="/docs/post-call/list-phone-call-hangup-status">
    Why the call ended
  </Card>

  <Card title="Retry failed calls" icon="arrow-rotate-right" href="/docs/outbound/auto-retry">
    Automatic retries
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.