Skip to main content
This reference covers common issues you may encounter when using the Telnyx CLI and how to resolve them.
Most CLI errors map directly to API error codes. For a complete list, see API Error Codes.

​
Authentication Errors

​
”Unauthorized” (401)

Error: Request failed with status 401: Unauthorized
Causes:
  • Invalid or expired API key
  • API key not set
  • API key has extra whitespace or characters
Solutions:
  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

Causes:
  • Environment variable not set
  • Environment variable not exported
Solutions:
  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
Causes:
  • API key doesn’t have permission for this action
  • Resource belongs to a different account
  • Account verification required
Solutions:
  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
Causes:
  • Resource ID is incorrect
  • Resource was deleted
  • Resource belongs to a different account
Solutions:
  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”

Solution: List your numbers to see what’s available: 
telnyx phone-numbers list

​
Rate Limiting

​
”Too Many Requests” (429)

Error: Request failed with status 429: Too Many Requests
Causes:
  • Exceeded API rate limits
  • Too many requests in short period
Solutions:
  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
Solutions:
  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
Solution: Register for 10DLC via the Portal or API. See the 10DLC documentation.

​
”Invalid ‘to’ number”

Error: The 'to' phone number is invalid
Solutions:
  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”

Causes:
  • CLI not installed
  • Go bin directory not in PATH
  • Shell not reloaded after install
Solutions:
  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”

Causes:
  • Go not installed
Solutions: Install Go: 
# 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
Solution: Upgrade Go: 
# macOS
brew upgrade go

# Or download latest from go.dev

​
Build/compile errors

Solutions:
  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

Causes:
  • No internet connection
  • Firewall blocking requests
  • Proxy misconfiguration
Solutions:
  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

Solutions:
  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

For detailed HTTP request/response logging: 
telnyx phone-numbers list --debug

​
Check CLI Version

Ensure you’re on the latest version: 
telnyx --version

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

​
Get Support