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

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, the underlying SBC only accepts IPv4 addresses. When you provide a hostname, the SBC rejects the gateway configuration.

How to check

Look at the value you passed in gateways[].ip. If it contains letters (for example, sip.example.com), it is a hostname. The SBC needs a numeric IPv4 address instead.

How to fix

Resolve the hostname to its IPv4 address, then use that IP directly.

$
dig +short sip.example.com A

$
nslookup sip.example.com

1
{
2
  "provider": "byo-sip-trunk",
3
  "name": "my sip trunk",
4
  "gateways": [
5
    {
6
      "ip": "203.0.113.10",
7
      "port": 5060,
8
      "outboundEnabled": true,
9
      "inboundEnabled": false
10
    }
11
  ]
12
}

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:

1
{
2
  "provider": "byo-sip-trunk",
3
  "name": "my sip trunk",
4
  "gateways": [
5
    {
6
      "ip": "203.0.113.10",
7
      "port": 5060,
8
      "outboundEnabled": true,
9
      "inboundEnabled": false
10
    }
11
  ]
12
}

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:

Gateway configuration reference

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

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