Troubleshooting Guide

This guide helps you diagnose and resolve common issues with the Audian API.

Authentication Issues

Error: "invalid_api_key"

Symptom: All API requests return 401 Unauthorized with message "The API key provided is invalid"

Causes:

1. API key is missing from the request
2. API key is malformed or expired
3. API key is for the wrong environment (test vs. live)
4. API key has been revoked

Diagnosis:

# Check if API key is set
echo $AUDIAN_API_KEY

# Verify API key format (should start with 'sk_live_' or 'sk_test_')
echo $AUDIAN_API_KEY | grep -E '^sk_(live|test)_'

Solutions:

1. Verify API Key Exists

const apiKey = process.env.AUDIAN_API_KEY;
if (!apiKey) {
  throw new Error('AUDIAN_API_KEY environment variable not set');
}

2. Check API Key Format

# Correct format
sk_live_XXXXXXXXXXXXXXXXXXXX
sk_test_XXXXXXXXXXXXXXXXXXXX

3. Regenerate API Key

• Log in to your Audian Dashboard
• Go to Settings > API Keys
• Click "Regenerate" to create a new key
• Update your environment variables

4. Verify Authorization Header

curl -H "X-Auth-Token: sk_live_..." https://api.audian.com:8443/v2/numbers

Error: "missing_authentication"

Symptom: API requests return 401 Unauthorized with message "Authentication credentials were not provided"

Cause: The Authorization header is missing or improperly formatted

Solution:

Ensure the Authorization header is included:

curl \
  -H "X-Auth-Token: YOUR_API_KEY" \
  https://api.audian.com:8443/v2/numbers

JavaScript SDK:

const client = new AudianClient({
  apiKey: 'YOUR_API_KEY'
});

Request Validation Issues

Error: "invalid_phone_number"

Symptom: Phone number operations fail with "The phone number must be in E.164 format"

Valid Formats:

• E.164 (International standard): +14155551234
• Must start with +
• Must include country code (1 for US/Canada)
• No spaces, dashes, or parentheses

Common Mistakes:

Invalid	Valid	Notes
415-555-1234	+14155551234	Remove formatting
(415) 555-1234	+14155551234	Remove parentheses
1-415-555-1234	+14155551234	Remove hyphens, add +
4155551234	+14155551234	Add + and country code

Solution:

function formatPhoneNumber(input) {
  // Remove all non-digit characters except +
  let digits = input.replace(/[^\d+]/g, '');

  // If doesn't start with +, assume US
  if (!digits.startsWith('+')) {
    digits = '+1' + digits.replace(/^1/, '');
  }

  return digits;
}

// Test
console.log(formatPhoneNumber('415-555-1234')); // +14155551234
console.log(formatPhoneNumber('(415) 555-1234')); // +14155551234
console.log(formatPhoneNumber('4155551234')); // +14155551234

Error: "invalid_location"

Symptom: Number search fails with "The location must be in format: country-state-areacode"

Valid Location Formats:

• US-CA-415 (Country-State-Area Code)
• US-NY (Country-State)
• US (Country only)

Common Mistakes:

Invalid	Valid	Notes
California	US-CA	Use state abbreviation
CA-415	US-CA-415	Include country code
USA-CA	US-CA	Use country code (US, CA, GB, etc.)
415	US-CA-415	Include country and state

Solution:

function validateLocation(location) {
  const parts = location.split('-');

  if (parts.length < 1 || parts.length > 3) {
    throw new Error('Invalid location format');
  }

  // Check country code (2-3 characters)
  if (parts[0].length < 2 || parts[0].length > 3) {
    throw new Error('Invalid country code');
  }

  // Check state code if provided (2 characters)
  if (parts.length > 1 && parts[1].length !== 2) {
    throw new Error('Invalid state code');
  }

  // Check area code if provided (3 digits)
  if (parts.length > 2 && !/^\d{3}$/.test(parts[2])) {
    throw new Error('Invalid area code');
  }

  return true;
}

Rate Limiting Issues

Error: "rate_limit_error"

Symptom: API requests fail with HTTP 429 "Too many requests"

Causes:

1. Requests exceed rate limit (e.g., 1000/hour)
2. Monthly request quota exceeded
3. Burst rate limit exceeded

Diagnosis:

// Check rate limit headers
const response = await client.numbers.list();
console.log('Limit:', response.headers['x-ratelimit-limit']);
console.log('Remaining:', response.headers['x-ratelimit-remaining']);
console.log('Reset:', new Date(response.headers['x-ratelimit-reset'] * 1000));

Solutions:

1. Implement Exponential Backoff

async function requestWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429) {
        const retryAfter = parseInt(error.headers['retry-after'] || '60');
        console.log(`Rate limited. Waiting ${retryAfter}s...`);
        await sleep(retryAfter * 1000);
      } else {
        throw error;
      }
    }
  }
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

2. Implement Request Queuing

class RequestQueue {
  constructor(rateLimit = 1000, interval = 3600000) {
    this.rateLimit = rateLimit;
    this.interval = interval;
    this.requests = [];
  }

  async execute(fn) {
    const now = Date.now();
    this.requests = this.requests.filter(t => now - t < this.interval);

    if (this.requests.length >= this.rateLimit) {
      const oldest = this.requests[0];
      const waitTime = this.interval - (now - oldest);
      await sleep(waitTime);
    }

    this.requests.push(Date.now());
    return await fn();
  }
}

// Usage
const queue = new RequestQueue(1000, 3600000); // 1000 requests/hour

const numbers = await queue.execute(() =>
  client.numbers.search({ location: 'US-CA-415' })
);

3. Cache Responses

class CacheLayer {
  constructor(ttl = 300000) { // 5 minutes
    this.cache = new Map();
    this.ttl = ttl;
  }

  async get(key, fn) {
    const cached = this.cache.get(key);

    if (cached && Date.now() - cached.time < this.ttl) {
      return cached.data;
    }

    const data = await fn();
    this.cache.set(key, { data, time: Date.now() });
    return data;
  }
}

// Usage
const cache = new CacheLayer();

const numbers = await cache.get('numbers-us-ca-415', () =>
  client.numbers.search({ location: 'US-CA-415' })
);

4. Contact Support to Increase Limits

• Log in to Audian Dashboard
• Go to Settings > Rate Limits
• Request higher limits
• Provide use case details

Resource Not Found Issues

Error: "not_found_error"

Symptom: API requests return 404 "The requested resource was not found"

Common Causes:

1. Resource ID is incorrect
2. Resource has been deleted
3. Resource belongs to a different account
4. Resource ID format is wrong

Diagnosis:

// Verify resource exists
try {
  const number = await client.numbers.get('num_abc123');
  console.log('Resource found:', number);
} catch (error) {
  if (error.code === 'not_found_error') {
    console.log('Resource not found');
    // List all numbers to verify ID
    const all = await client.numbers.list();
    console.log('Available numbers:', all.data.numbers);
  }
}

Solutions:

1. Verify Resource ID

// List all numbers to find the correct ID
const response = await client.numbers.list({ limit: 100 });
const numberIds = response.data.numbers.map(n => n.id);
console.log('Available IDs:', numberIds);

// Use the correct ID
const number = await client.numbers.get(numberIds[0]);

2. Check Resource Ownership

// Verify the resource belongs to your account
const response = await client.numbers.list({
  limit: 100,
  status: 'active'
});

const owned = response.data.numbers.find(n => n.id === 'num_abc123');
if (!owned) {
  console.log('This number is not owned by your account');
}

Payment and Billing Issues

Error: "insufficient_funds"

Symptom: Operations fail with HTTP 402 "Your account does not have sufficient funds"

Causes:

1. Account balance is too low
2. Payment method failed
3. Subscription expired
4. Credit limit exceeded

Solutions:

1. Check Account Balance

const account = await client.accounts.get();
console.log('Balance:', account.data.balance);
console.log('Credit Limit:', account.data.creditLimit);

2. Add Funds

• Log in to Audian Dashboard
• Go to Billing > Payment Methods
• Add a credit card or prepaid credits

3. Enable Auto-Recharge

• Go to Billing > Auto-Recharge
• Set up automatic payment when balance drops below threshold

Webhook Issues

Webhook Not Being Delivered

Causes:

1. Webhook endpoint is not returning 200 OK
2. Endpoint is timing out
3. Firewall blocking requests
4. Endpoint URL is incorrect

Diagnosis:

# Test webhook endpoint manually
curl -X POST https://your-domain.com/webhook \
  -H "Content-Type: application/json" \
  -H "X-Audian-Signature: whsig_..." \
  -d '{"type":"test","data":{}}'

# Should return 200 OK within 5 seconds

Solution:

// Webhook handler should respond quickly
app.post('/webhook', async (req, res) => {
  // Return 200 immediately
  res.status(200).json({ success: true });

  // Process webhook asynchronously
  processWebhookAsync(req.body).catch(console.error);
});

async function processWebhookAsync(event) {
  // Verify signature
  const verifier = new WebhookVerifier({ signingSecret: '...' });
  try {
    verifier.verify(event, signature);
  } catch (error) {
    console.error('Invalid signature');
    return;
  }

  // Handle event
  switch (event.type) {
    case 'sms.received':
      await handleSMS(event.data);
      break;
  }
}

Getting Help

If you're still experiencing issues:

1. Check Documentation: Review the relevant API endpoint documentation
2. Check Status Page: Visit status.audian.com for service status
3. Enable Debug Logging: Enable debug mode in the SDK
4. Contact Support: Email support@audian.com with:
   • API endpoint being used
   • Error code and message
   • Request ID (from response headers)
   • Steps to reproduce
   • Environment details (SDK version, language, OS)

Enable Debug Mode

JavaScript:

const client = new AudianClient({
  apiKey: 'YOUR_API_KEY',
  debug: true
});

Python:

import logging
logging.basicConfig(level=logging.DEBUG)

client = AudianClient(api_key='YOUR_API_KEY', debug=True)

Go:

client := audian.NewClient(
  audian.WithAPIKey("YOUR_API_KEY"),
  audian.WithDebug(true),
)