Troubleshooting

Troubleshooting #

Solutions to common issues when using the VoxPria REST API.

401 Unauthorized #

Solutions: #

• ✅ Verify your API key is correct (no extra spaces)
• ✅ Check you’re using Authorization: Bearer YOUR_KEY format
• ✅ Ensure the key hasn’t been revoked
• ✅ Confirm key format is agl_sk_...
• ✅ Create a new API key if needed

Test your key: #

curl -X GET "https://app.voxpria.com/api/v1/credits" \
  -H "Authorization: Bearer YOUR_API_KEY"

403 Forbidden #

Solutions: #

• ✅ Check your API key has required scopes
• ✅ For triggering calls: need calls:write scope
• ✅ For managing campaigns: need campaigns:write
• ✅ Create new key with correct scopes if needed

429 Too Many Requests #

Solutions: #

• ✅ Implement exponential backoff
• ✅ Check X-RateLimit-Reset header for retry time
• ✅ Reduce API call frequency
• ✅ Contact support for higher limits

Exponential Backoff Example: #

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.response?.status === 429 && i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
}

400 Bad Request #

Common Causes: #

• ❌ Missing required fields (agentId, toNumber)
• ❌ Invalid phone number format (must be E.164: +1234567890)
• ❌ Invalid JSON payload
• ❌ Wrong data types (string vs number)

Solutions: #

• ✅ Validate phone numbers: ^\+[1-9]\d{1,14}$
• ✅ Check all required fields are present
• ✅ Verify JSON is valid
• ✅ Review API documentation for endpoint requirements

500 Internal Server Error #

Solutions: #

• ✅ Retry the request after a few seconds
• ✅ Implement retry logic with backoff
• ✅ Check VoxPria status page for outages
• ✅ Contact support if error persists

Calls Not Connecting #

Check: #

• ✅ Phone number is valid and in E.164 format
• ✅ Number is not on do-not-call list
• ✅ Sufficient credits in account
• ✅ Agent is active and configured correctly
• ✅ Time zone and calling hours restrictions

Webhooks Not Received #

Verify: #

• ✅ Webhook URL is publicly accessible (HTTPS)
• ✅ Endpoint returns 200 status quickly
• ✅ No firewall blocking VoxPria IPs
• ✅ Webhook is active in dashboard
• ✅ Events are subscribed correctly

Test webhook locally: #

# Use ngrok to expose local server
ngrok http 3000

# Update webhook URL to ngrok URL
# Trigger a test call
# Check ngrok console for incoming webhooks

Invalid JSON Response #

Solutions: #

• ✅ Check response content-type is application/json
• ✅ Verify you’re parsing response correctly
• ✅ Look for error responses in different format
• ✅ Log raw response body for debugging

Environment-Specific Issues #

Development vs Production: #

• ✅ Use separate API keys per environment
• ✅ Don’t use production keys in development
• ✅ Test with small batches first
• ✅ Monitor credit usage closely

Getting Help #

If you’re still having issues:

Include in Support Request: #

• API endpoint you’re calling
• Request payload (remove sensitive data)
• Complete error response
• Timestamp of the issue
• API key ID (last 8 characters only)
• Programming language/framework