Troubleshooting Guide

Common issues and how to resolve them.

Authentication Issues

401 Unauthorized

  • Check if your token/API key has expired

  • Verify the Authorization header format: Bearer <token>

  • Ensure your API key is active (isActive: true)

  • Try refreshing your JWT token

403 Forbidden

  • Your account may lack the required permissions

  • Check if your organization status is active

  • Some endpoints require Staff role

Call Issues

Calls Not Connecting

  • Verify the contact's phone number format (E.164)

  • Check if the DID pool has valid numbers

  • Ensure the program has active status

  • Review dial timeout settings

Calls Going to Voicemail

  • Enable AMD (enableAMD: true) to detect voicemails

  • Configure the onVoicemail output in your Dial node

  • Consider calling at different times

Audio Not Playing

  • Verify the audio file exists and is valid

  • Check the audioId in your Play node

  • Ensure dictionary entries exist for dynamic content

Program Issues

Program Won't Start

  • Check if startAt is in the future

  • Verify the audience is not empty

  • Ensure the program status is active

  • Check for existing running executions

Program Stops Unexpectedly

  • scheduledStopAt may have been reached

  • All contacts may have been processed

  • Check for errors in the flow

Flow Issues

Flow Execution Fails

  • Validate your flow using POST /flows/validate

  • Check for missing node connections

  • Ensure all required outputs have targets

  • Verify variable names are correct

DTMF Input Not Recognized

  • Check timeout settings (default: 30000ms)

  • Verify allowedDigits configuration

  • Ensure multiDigitConfig terminators are correct

Rate Limiting

429 Too Many Requests

  • Reduce your request frequency

  • Implement exponential backoff

  • Consider batching operations

Contact Issues

Contacts Not Importing

  • Check phone number format (3-20 characters)

  • Verify required fields are present

  • Look for duplicate phone numbers (409 error)

Invalid Phone Number Errors

  • Use E.164 format: +[country code][number]

  • Ensure phone is 3-20 characters

  • Remove spaces and special characters

Still Need Help?

  1. Check the FAQ for more answers

  2. Review the API documentation

  3. Contact support with:

    • Organization ID

    • Error message/code

    • Steps to reproduce

    • Timestamp

PreviousGlossary

Last updated