Error codes

Use this page to understand why a call failed and what action to take next. Call failures usually come from the telephony layer, so the most useful value is the SIP status code shown in the call details. Twirp and HTTP codes may appear in technical details. These describe how the LiveKit API returned the failure. The SIP status explains the actual phone-call outcome.

How to read call errors

When an outbound call fails, the call detail page may show an error like:

480: Temporarily Unavailable

Technical details may include a Twirp wrapper like:

TwirpError(code=resource_exhausted, status=429, metadata={
  "sip_status_code": "480",
  "sip_status": "Temporarily Unavailable"
})

In this example:

Field	Meaning
`480`	SIP status code. This is the main call failure reason.
`Temporarily Unavailable`	SIP status text shown by the telephony provider.
`resource_exhausted`	Twirp error code returned by the LiveKit API.
`429`	HTTP status for the Twirp response.

Call failure codes

SIP code	Status	What it means	Recommended action	Agni tag
`480`	Temporarily Unavailable	The callee could not receive the call right now. The phone may be off, unreachable, out of coverage, or temporarily unable to accept calls.	Try again later. If it repeats, verify the number and carrier reachability.	`call_status:User Unavailable`
`486`	Busy Here	The callee is busy, already on another call, or the line rejected the call because it is occupied.	Try again later or call another number for the same contact.	`call_status:User Busy`
`408`	Request Timeout	The call timed out before the network or callee responded.	Try again. If it repeats, confirm the number and check telephony provider routing.	Not tagged automatically
`403`	Forbidden	The call was blocked by permission, routing, geo-permission, or provider policy.	Check phone number permissions, SIP trunk settings, and allowed destination countries.	Not tagged automatically
`404`	Not Found	The number or route could not be found by the carrier or telephony provider.	Confirm the phone number is valid and in E.164 format.	Not tagged automatically
`487`	Request Terminated	The call attempt was cancelled before it connected.	Retry the call. Check whether the campaign or user cancelled the attempt.	Not tagged automatically
`500`	Server Error	A provider or telephony service returned an internal error.	Retry after a short delay. Contact support if the issue continues.	Not tagged automatically
`503`	Service Unavailable	The carrier or telephony service was temporarily unavailable.	Retry later. Check provider status if many calls fail at once.	Not tagged automatically
`603`	Decline	The callee or carrier declined the call.	Try again later or use another contact method.	Not tagged automatically

Twirp error wrapper

Some call failures are returned through a Twirp error wrapper. For call troubleshooting, use the SIP metadata first.

Twirp code	HTTP status	What it usually means in call failures
`resource_exhausted`	`429`	LiveKit returned the SIP failure through a resource-exhausted response. Check `sip_status_code` and `sip_status` in metadata.
`unauthenticated`	`401`	The LiveKit API credentials were missing or invalid. Check `LIVEKIT_API_KEY` and `LIVEKIT_API_SECRET`.
`permission_denied`	`403`	The credentials are valid, but the request is not allowed. Check permissions and SIP trunk access.
`not_found`	`404`	The requested room, trunk, participant, or API route was not found.
`unavailable`	`503`	The LiveKit API or a dependent service was temporarily unavailable. Retry later.
`internal`	`500`	An internal service error occurred. Retry and contact support if it continues.

Agni currently adds automatic call-status tags for 480 Temporarily Unavailable and 486 Busy Here. Other errors may still appear in technical details, but they are not mapped to custom call-status tags yet.

What to include when contacting support

When you contact support about a failed call, include:

The call ID or session ID
The phone number or contact involved
The visible error code and status
The Twirp code and HTTP status, if shown
The timestamp of the failed call

This helps support identify whether the issue came from the number, carrier, SIP trunk, LiveKit API, or Agni configuration.

Welcome to Agni

Getting Started

Platform

Builder

Campaign

Management

Operation

Resources

Error codes

Error codes

How to read call errors

Call failure codes

Twirp error wrapper

What to include when contacting support

​Error codes

​How to read call errors

​Call failure codes

​Twirp error wrapper

​What to include when contacting support

Error codes

How to read call errors

Call failure codes

Twirp error wrapper

What to include when contacting support