Messaging Error Code Reference

import telnyx

telnyx.api_key = "YOUR_API_KEY"

try:
    message = telnyx.Message.create(
        from_="+18005550100",
        to="+18005550101",
        text="Hello!",
        messaging_profile_id="YOUR_PROFILE_ID"
    )
    print(f"Sent: {message.id}")

except telnyx.error.InvalidRequestError as e:
    # API request errors (40xxx)
    error = e.json_body.get("errors", [{}])[0]
    code = error.get("code", "unknown")
    detail = error.get("detail", "No details")

    if code == "40300":
        print(f"Recipient opted out (STOP). Do not retry.")
    elif code == "40333":
        print(f"Spend limit reached. Increase limit or wait for reset.")
    elif code == "40310":
        print(f"Invalid destination number. Check E.164 format.")
    else:
        print(f"Error {code}: {detail}")

except telnyx.error.AuthenticationError:
    print("Invalid API key")

const telnyx = require("telnyx")("YOUR_API_KEY");

try {
  const message = await telnyx.messages.create({
    from: "+18005550100",
    to: "+18005550101",
    text: "Hello!",
    messaging_profile_id: "YOUR_PROFILE_ID",
  });
  console.log(`Sent: ${message.data.id}`);
} catch (err) {
  const error = err.rawType || "unknown";
  const detail = err.message;

  switch (error) {
    case "40300":
      console.log("Recipient opted out (STOP). Do not retry.");
      break;
    case "40333":
      console.log("Spend limit reached.");
      break;
    case "40310":
      console.log("Invalid destination number.");
      break;
    default:
      console.log(`Error ${error}: ${detail}`);
  }
}

require "telnyx"

Telnyx.api_key = "YOUR_API_KEY"

begin
  message = Telnyx::Message.create(
    from: "+18005550100",
    to: "+18005550101",
    text: "Hello!",
    messaging_profile_id: "YOUR_PROFILE_ID"
  )
  puts "Sent: #{message.id}"

rescue Telnyx::InvalidRequestError => e
  error = e.json_body&.dig(:errors, 0) || {}
  code = error[:code] || "unknown"
  detail = error[:detail] || "No details"

  case code
  when "40300"
    puts "Recipient opted out. Do not retry."
  when "40333"
    puts "Spend limit reached."
  else
    puts "Error #{code}: #{detail}"
  end
end

package main

import (
    "context"
    "fmt"
    "strings"

    telnyx "github.com/telnyx/telnyx-go"
)

func main() {
    client := telnyx.NewClient("YOUR_API_KEY")

    _, err := client.Messages.Create(context.Background(), &telnyx.MessageParams{
        From:               "+18005550100",
        To:                 "+18005550101",
        Text:               "Hello!",
        MessagingProfileID: "YOUR_PROFILE_ID",
    })
    if err != nil {
        if strings.Contains(err.Error(), "40300") {
            fmt.Println("Recipient opted out. Do not retry.")
        } else if strings.Contains(err.Error(), "40333") {
            fmt.Println("Spend limit reached.")
        } else {
            fmt.Printf("Error: %v\n", err)
        }
        return
    }
    fmt.Println("Message sent successfully")
}

# Check response for errors
response=$(curl -s -w "\n%{http_code}" -X POST https://api.telnyx.com/v2/messages \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+18005550100",
    "to": "+18005550101",
    "text": "Hello!"
  }')

http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | head -n -1)

if [ "$http_code" != "200" ]; then
  error_code=$(echo "$body" | python3 -c "import sys,json; print(json.load(sys.stdin).get('errors',[{}])[0].get('code','unknown'))")
  echo "Error $error_code (HTTP $http_code)"
  echo "$body" | python3 -m json.tool
fi