VapiAI · bajajcodes · Feb 9, 2026 · Feb 9, 2026
diff --git a/fern/advanced/sip/troubleshoot-sip-trunk-credential-errors.mdx b/fern/advanced/sip/troubleshoot-sip-trunk-credential-errors.mdx
@@ -0,0 +1,184 @@
+---
+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
+
+<Note>
+  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.
+</Note>
+
+## 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.
+
+<Steps>
+<Step title="Look up the IP address">
+
+Run one of the following commands to resolve your SIP provider's hostname to an IPv4 address:
+
+```bash title="Terminal"
+dig +short sip.example.com A
+```
+
+```bash title="Terminal (alternative)"
+nslookup sip.example.com
+```
+
+This returns one or more IPv4 addresses, for example `203.0.113.10`.
+
+</Step>
+
+<Step title="Use the resolved IP in your API request">
+
+Replace the hostname with the numeric IPv4 address in your gateway configuration:
+
+```json title="Gateway configuration"
+{
+  "provider": "byo-sip-trunk",
+  "name": "my sip trunk",
+  "gateways": [
+    {
+      "ip": "203.0.113.10",
+      "port": 5060,
+      "outboundEnabled": true,
+      "inboundEnabled": false
+    }
+  ]
+}
+```
+
+</Step>
+</Steps>
+
+<Note>
+  Always use the IPv4 address, not the hostname. If your provider's IP changes,
+  you need to update the gateway configuration.
+</Note>
+
+## 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:
+
+```json title="Gateway configuration"
+{
+  "provider": "byo-sip-trunk",
+  "name": "my sip trunk",
+  "gateways": [
+    {
+      "ip": "203.0.113.10",
+      "port": 5060,
+      "outboundEnabled": true,
+      "inboundEnabled": false
+    }
+  ]
+}
+```
+
+<Tip>
+  If you are using the Vapi dashboard, uncheck the **Inbound** option when
+  configuring the gateway.
+</Tip>
+
+## 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`   |
+
+<Warning>
+  Both addresses must be allowed. Vapi may use either one for signaling, so
+  missing one can cause intermittent failures.
+</Warning>
+
+## Gateway configuration reference
+
+The table below lists all available options for each entry in the `gateways` array.
+
+| Option               | Type    | Default   | Description                                                                    |
+| -------------------- | ------- | --------- | ------------------------------------------------------------------------------ |
+| `ip`                 | string  | (required)| IPv4 address of your SIP gateway. Must be a numeric IP address, not a hostname.|
+| `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](/advanced/sip/sip-trunk) guide to verify your configuration end-to-end
+- **Configure a provider:** Set up your SIP trunk with a specific provider such as [Twilio](/advanced/sip/sip-twilio), [Telnyx](/advanced/sip/sip-telnyx), [Zadarma](/advanced/sip/sip-zadarma), or [Plivo](/advanced/sip/sip-plivo)
+- **Learn about SIP telephony:** Explore the [SIP telephony](/advanced/sip/sip) overview for broader SIP integration options
diff --git a/fern/docs.yml b/fern/docs.yml
@@ -407,6 +407,8 @@ navigation:
                     path: advanced/sip/sip-zadarma.mdx
                   - page: Plivo
                     path: advanced/sip/sip-plivo.mdx
+              - page: Troubleshoot SIP trunk credential errors
+                path: advanced/sip/troubleshoot-sip-trunk-credential-errors.mdx
           - page: Phone Number Hooks
             path: phone-numbers/phone-number-hooks.mdx
             icon: fa-light fa-webhook