troubleshoot-sip-trunk-credential-errors.mdx

title	Troubleshoot SIP trunk credential errors
subtitle	Learn to resolve gateway creation failures when setting up a BYO SIP trunk
slug	advanced/sip/troubleshoot-sip-trunk-credential-errors

Overview

This guide helps you resolve the Couldn't validate SIP trunk credential. SIP gateway creation failed. error when creating a BYO SIP trunk credential in Vapi.

This error occurs during the gateway creation step of SIP trunk provisioning. Vapi's SBC (Session Border Controller) rejects the gateway configuration you provided. The sections below cover the most common causes and how to fix each one.

In this guide, you'll learn to:

• Identify the three most common causes of SIP trunk credential validation failures
• Resolve hostname-vs-IP, inbound-flag, and IP-allowlist issues
• Verify your gateway configuration against the full parameter reference

This guide focuses on the specific `SIP gateway creation failed` error. For general SIP trunk setup instructions, see the [SIP trunking](/advanced/sip/sip-trunk) page.

Prerequisites

Before you start troubleshooting, ensure you have:

• A Vapi account with API access
• Your SIP provider's server address, username, and password
• Access to your SIP provider's admin panel (to check IP whitelisting)

Using a hostname instead of an IP address

This is the most common cause of this error.

What happens

Vapi's API accepts both hostnames (for example, sip.example.com) and IPv4 addresses (for example, 203.0.113.10) in the gateways[].ip field. However, hostnames only work for outbound-only gateways. For inbound-enabled gateways, the SBC requires a numeric IPv4 address to match the origin of incoming SIP requests. When you provide a hostname for an inbound-enabled gateway, the SBC rejects the gateway configuration.

How to check

Look at the value you passed in gateways[].ip and the inboundEnabled setting:

• If inboundEnabled is true (the default) and gateways[].ip contains a hostname (for example, sip.example.com), this is the problem. Inbound gateways require a numeric IPv4 address.
• If inboundEnabled is false (outbound-only), hostnames are accepted and this is not the cause of your error.

How to fix

If your gateway has inbound enabled, resolve the hostname to its IPv4 address, then use that IP directly.

Run one of the following commands to resolve your SIP provider's hostname to an IPv4 address:

dig +short sip.example.com A

nslookup sip.example.com

This returns one or more IPv4 addresses, for example 203.0.113.10.

Replace the hostname with the numeric IPv4 address in your gateway configuration:

{
  "provider": "byo-sip-trunk",
  "name": "my sip trunk",
  "gateways": [
    {
      "ip": "203.0.113.10",
      "port": 5060,
      "outboundEnabled": true,
      "inboundEnabled": true
    }
  ]
}

Hostnames are supported for outbound-only gateways (`inboundEnabled: false`). For inbound-enabled gateways, always use a numeric IPv4 address. If your provider's IP changes, you need to update the gateway configuration.

Inbound enabled on an outbound-only trunk

What happens

The inboundEnabled gateway option defaults to true. If your SIP trunk is outbound-only (you only make calls through it, you do not receive inbound calls through Vapi), having inbound enabled can cause gateway creation to fail with some providers.

How to check

Look at your API request. If you did not set inboundEnabled explicitly, it defaulted to true. If you only need outbound calling, this is likely the problem.

How to fix

Set inboundEnabled to false in your gateway configuration:

{
  "provider": "byo-sip-trunk",
  "name": "my sip trunk",
  "gateways": [
    {
      "ip": "203.0.113.10",
      "port": 5060,
      "outboundEnabled": true,
      "inboundEnabled": false
    }
  ]
}

If you are using the Vapi dashboard, uncheck the **Inbound** option when configuring the gateway.

Carrier IP allowlist not configured

What happens

Your SIP provider needs to allow traffic from Vapi's SBC IP addresses. If these IPs are not on the allowlist, the SBC's registration and signaling requests to your provider are blocked, and gateway creation fails.

How to check

Ask your SIP provider whether the following IP addresses are on their allowlist:

• 44.229.228.186/32
• 44.238.177.138/32

How to fix

Ask your SIP provider to add both Vapi SBC IP addresses to their allowlist:

IP address	Netmask
44.229.228.186	/32
44.238.177.138	/32

Both addresses must be allowed. Vapi may use either one for signaling, so missing one can cause intermittent failures.

Gateway configuration reference

The table below lists all available options for each entry in the gateways array.

Option	Type	Default	Description
ip	string	(required)	Server address of your SIP gateway. Use a numeric IPv4 address for inbound-enabled gateways. Hostnames are accepted for outbound-only gateways (inboundEnabled: false).
port	number	5060	SIP signaling port.
netmask	number	32	Subnet mask for inbound IP matching. Valid range: 24 to 32.
inboundEnabled	boolean	true	Whether this gateway accepts inbound calls. Set to false for outbound-only trunks.
outboundEnabled	boolean	true	Whether outbound calls route through this gateway.
outboundProtocol	string	"udp"	Signaling protocol. Options: udp, tcp, tls, tls/srtp.
optionsPingEnabled	boolean	false	Whether to send SIP OPTIONS pings to check if the gateway is reachable.

If the error persists

If none of the above resolves your issue, gather the following information and contact Vapi support:

• Your organization ID
• The exact error message you received
• The full request payload you sent (redact the password)
• Your SIP provider name and server address
• Whether you are setting up for inbound calls, outbound calls, or both

Next steps

Now that you can troubleshoot SIP trunk credential errors:

• Review SIP trunk setup: Follow the complete SIP trunking guide to verify your configuration end-to-end
• Configure a provider: Set up your SIP trunk with a specific provider such as Twilio, Telnyx, Zadarma, or Plivo
• Learn about SIP telephony: Explore the SIP telephony overview for broader SIP integration options