API

Errors and troubleshooting matrix

Resolve all HTTP status codes and operational error messages without contacting support.

Interactive Troubleshooting

💡

For live interactive testing and zero-contact troubleshooting, visit the interactive explorer at /docs/api.

HTTP status code reference

Status	Meaning	Immediate action
400	Bad Request	Fix parameter types or phone formatting (ensure E.164 format with + country code).
401	Unauthorized	Verify API key in 'Authorization: Bearer avp_...' or regenerate a fresh key.
403	Forbidden	API key lacks required scope (e.g. 'calls:trigger' required for outbound calling).
404	Not Found	Resource ID does not exist or belongs to a different organization.
409	Conflict	Telephony or capacity conflict (outbound number not ready or wallet balance low).
429	Rate Limited	Retry with exponential backoff and jitter.
5xx	Server Error	Temporary gateway issue. Retry idempotent requests after a delay.

Zero-contact error resolution matrix

Error message	Root cause	Exact 3-step fix
Import or buy a phone number with Outbound or Both direction...	Agent has no Ready phone number configured for outbound calling.	1. Open Dashboard → Phone Numbers. 2. Ensure your number has Direction 'Outbound' or 'Both'. 3. Assign it to this agent and click Save.
Destination must be formatted as an E.164 phone number	Phone number is missing country code or plus sign.	1. Format with '+' and country code (e.g. '+919876543210' for India, '+14155552671' for US). 2. Strip spaces, dashes, and parentheses. 3. Validate with libphonenumber or regex before calling.
The selected outbound number changed. Refresh phone numbers before calling.	Channel admission lock due to active concurrent call on the same number.	1. Wait 5 seconds for the active call to complete. 2. Or purchase additional phone numbers in Dashboard → Phone Numbers. 3. Or enable multi-channel SIP trunking.
Invalid or expired API key.	The API key was revoked, expired, or mistyped.	1. Go to Dashboard → Developers → API Keys. 2. Create a new key. 3. Update your environment variable and restart your server.
API key lacks 'calls:trigger' scope	The key was issued with 'read' scope only.	1. Go to Dashboard → Developers. 2. Create an API key with 'calls:trigger' or 'full-access' scope. 3. Replace the token in your backend.

Exponential backoff implementation

For 429 and temporary 5xx errors, implement bounded exponential backoff with jitter:

javascript

async function fetchWithRetry(url, options, maxRetries = 4) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      if (response.status !== 429 && response.status < 500) {
        return response;
      }
    } catch (err) {
      if (attempt === maxRetries) throw err;
    }
    const delay = Math.pow(2, attempt) * 1000 + Math.random() * 500;
    await new Promise((r) => setTimeout(r, delay));
  }
}