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 configured
  • Using wrong profile
Solutions:
  1. Verify your API key is correct: 
    telnyx auth status
  2. Re-run setup if needed: 
    telnyx auth setup
  3. Check if environment variable is overriding config: 
    echo $TELNYX_API_KEY
unset TELNYX_API_KEY  # Clear if set incorrectly
  4. Verify the key in the Telnyx Portal

​
”No configuration found”

Error: No configuration found. Run 'telnyx auth setup' first.
Solution: 
telnyx auth setup
Or set the environment variable: 
export TELNYX_API_KEY=KEY_xxxxxxxxxxxxx

​
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 profile: 
    telnyx auth status
telnyx <command> --profile <correct-profile>
  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 number list
telnyx messaging-profile list
  2. Check for typos in the resource ID
  3. Ensure you’re using the correct profile if you have multiple accounts

​
”Phone number not found”

Error: Phone number +15551234567 not found in your account
Solution: List your numbers to see what’s available: 
telnyx number 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 message 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: 
    telnyx number update +15551234567 --messaging-profile-id <id>
  2. Or purchase a messaging-enabled number: 
    telnyx number search --country US --features sms

​
“10DLC campaign required”

Error: US A2P messaging requires 10DLC registration
Solution: Register for 10DLC: 
telnyx 10dlc wizard
Or 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 message send --to 5551234567 ...

# Correct
telnyx message send --to +15551234567 ...
  2. Verify the number is valid: 
    telnyx lookup +15551234567

​
Installation Issues

​
”command not found: telnyx”

Causes:
  • CLI not installed
  • Not in PATH
  • Shell not reloaded after install
Solutions:
  1. Verify installation: 
    npm list -g @telnyx/api-cli
  2. Reinstall if needed: 
    npm install -g @telnyx/api-cli
  3. Check npm global bin is in PATH: 
    npm config get prefix
# Add <prefix>/bin to your PATH
  4. Restart your terminal or reload shell config: 
    source ~/.bashrc  # or ~/.zshrc

​
Node.js version error

Error: The CLI requires Node.js 20 or later
Solution: Upgrade Node.js: 
# Using nvm
nvm install 20
nvm use 20

# Using Homebrew
brew install node@20

​
Permission denied during install

Error: EACCES: permission denied
Solutions:
  1. Fix npm permissions (npm guide)
  2. Or use a Node version manager (nvm, fnm) which doesn’t require sudo

​
Connection Issues

​
”Network error” / “ECONNREFUSED”

Error: connect ECONNREFUSED
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

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

​
JSON Parsing Errors

​
”Unexpected token in JSON”

Error: Unexpected token < in JSON at position 0
Causes:
  • API returned HTML error page instead of JSON
  • Authentication issue returning login page
Solution: Check authentication and try again: 
telnyx auth status
telnyx auth setup  # if needed

​
Getting More Help

​
Enable Debug Mode

For detailed request/response logging: 
DEBUG=* telnyx number list

​
Check CLI Version

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

# Update
npm update -g @telnyx/api-cli

​
Get Support