Telnyx CLI troubleshooting

​

Authentication Errors

​

”Unauthorized” (401)

Error: Request failed with status 401: Unauthorized

• Invalid or expired API key
• API key not set
• API key has extra whitespace or characters

1. Verify your API key is set:
   echo $TELNYX_API_KEY
   
2. Check the key format (should start with KEY_):
   # Correct format
   export TELNYX_API_KEY=KEY_xxxxxxxxxxxxx
   
3. Verify the key in the Telnyx Portal
4. Test with a simple command:
   telnyx balance retrieve
   

​

“No API key” Error

• Environment variable not set
• Environment variable not exported

1. Set the environment variable:
   export TELNYX_API_KEY=KEY_xxxxxxxxxxxxx
   
2. Verify it’s exported (not just set):
   # Wrong (not exported)
   TELNYX_API_KEY=KEY_xxx
   
   # Correct (exported)
   export TELNYX_API_KEY=KEY_xxx
   
3. Add to your shell profile for persistence:
   echo 'export TELNYX_API_KEY=KEY_xxx' >> ~/.bashrc
   source ~/.bashrc
   

​

Permission Errors

​

”Forbidden” (403)

Error: Request failed with status 403: Forbidden

• API key doesn’t have permission for this action
• Resource belongs to a different account
• Account verification required

1. Check API key permissions in the Portal
2. Verify you’re using the correct API key for the account
3. Some features require account verification (verify here)

​

Resource Errors

​

”Not Found” (404)

Error: Request failed with status 404: Not Found

• Resource ID is incorrect
• Resource was deleted
• Resource belongs to a different account

1. Verify the resource exists:
   telnyx phone-numbers list
   telnyx messaging-profiles list
   
2. Check for typos in the resource ID
3. Ensure you’re using the correct API key if you have multiple accounts

​

”Phone number not found”

telnyx phone-numbers list

​

Rate Limiting

​

”Too Many Requests” (429)

Error: Request failed with status 429: Too Many Requests

• Exceeded API rate limits
• Too many requests in short period

1. Add delays between requests in scripts:
   for number in "${NUMBERS[@]}"; do
     telnyx messages send --from "$FROM" --to "$number" --text "$MSG"
     sleep 0.5  # Add delay
   done
   
2. Use bulk endpoints when available
3. Check rate limits documentation

​

Messaging Errors

​

”Number not enabled for messaging”

Error: The phone number +15551234567 is not enabled for messaging

1. Enable messaging on the number via the Portal or API
2. Or purchase a messaging-enabled number:
   telnyx available-phone-numbers list --filter.country-code US --filter.features sms
   

​

“10DLC campaign required”

Error: US A2P messaging requires 10DLC registration

​

”Invalid ‘to’ number”

Error: The 'to' phone number is invalid

1. Use E.164 format (include country code):
   # Wrong
   telnyx messages send --to 5551234567 ...
   
   # Correct
   telnyx messages send --to +15551234567 ...
   
2. Verify the number is valid:
   telnyx number-lookup retrieve --phone-number +15551234567
   

​

Installation Issues

​

”command not found: telnyx”

• CLI not installed
• Go bin directory not in PATH
• Shell not reloaded after install

1. Verify Go’s bin directory contains telnyx:
   ls $(go env GOPATH)/bin/telnyx
   
2. Add Go bin to PATH:
   export PATH="$PATH:$(go env GOPATH)/bin"
   
3. Reinstall if needed:
   go install github.com/team-telnyx/telnyx-cli/cmd/telnyx@latest
   
4. Reload your shell config:
   source ~/.bashrc  # or ~/.zshrc
   

​

“command not found: go”

• Go not installed

# macOS
brew install go

# Linux (Debian/Ubuntu)
sudo apt install golang-go

# Or download from go.dev
# https://go.dev/dl/

​

Go version error

Error: requires go >= 1.22

# macOS
brew upgrade go

# Or download latest from go.dev

​

Build/compile errors

1. Ensure you have Go 1.22+:
   go version
   
2. Clear module cache and retry:
   go clean -modcache
   go install github.com/team-telnyx/telnyx-cli/cmd/telnyx@latest
   

​

Connection Issues

​

Network error / Connection refused

• No internet connection
• Firewall blocking requests
• Proxy misconfiguration

1. Check internet connectivity
2. Verify you can reach the API:
   curl -I https://api.telnyx.com/v2
   
3. Check proxy settings if applicable

​

Timeout errors

1. Check your internet connection
2. Try again (may be temporary)
3. For large operations, the API may need more time

​

Getting More Help

​

Enable Debug Mode

telnyx phone-numbers list --debug

​

Check CLI Version

telnyx --version

# Update to latest
go install github.com/team-telnyx/telnyx-cli/cmd/telnyx@latest

​

Get Support

• GitHub Issues: Report bugs
• Telnyx Support: Contact support
• Community: Slack
• API Status: status.telnyx.com