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
• Understand when hostnames work (outbound) and when they don’t (inbound)
• 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 for an inbound gateway

This is the most common cause of this error.

What happens

The gateways[].ip field accepts both hostnames (for example, sip.example.com) and IPv4 addresses (for example, 203.0.113.10). However, the behavior differs depending on the call direction:

• Outbound gateways — Hostnames and IPv4 addresses both work. Vapi resolves the hostname when routing outbound calls to your SIP provider.
• Inbound gateways — Only IPv4 addresses work. The SBC needs a numeric IP address to match incoming SIP requests to your trunk. When you provide a hostname with inboundEnabled: true, the SBC rejects the gateway configuration.

How to check

Look at your gateway configuration. If inboundEnabled is true (or omitted, since it defaults to true) and the ip field contains a hostname (for example, sip.example.com), this is the cause of the error.

How to fix

You have two options depending on whether you need inbound calling:

If you need inbound calling, resolve the hostname to its IPv4 address:

$
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": true
10
    }
11
  ]
12
}

If you only need outbound calling, you can keep the hostname and disable inbound:

1
{
2
  "provider": "byo-sip-trunk",
3
  "name": "my sip trunk",
4
  "gateways": [
5
    {
6
      "ip": "sip.example.com",
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