Troubleshooting

This guide covers common issues you may encounter when integrating with HMS Sovereign and how to resolve them.

Authentication Issues

401 Unauthorized

Symptom: All API requests return 401 Unauthorized.

Possible Causes:

Missing Authorization header
Invalid API key
API key has been revoked

Solution:

Verify your API key is correct
Ensure the header format is Authorization: Bearer YOUR_API_KEY
Check if the key is active in Settings > API Keys
Generate a new key if needed

# Correct format
curl https://api.hmsovereign.com/api/v1/account \
  -H "Authorization: Bearer fl_live_abc123..."

403 Forbidden

Symptom: Request returns 403 Forbidden.

Possible Causes:

Trying to access another organization's resources
Resource doesn't belong to your organization

Solution: Verify the resource ID belongs to your organization by listing your resources first.

Call Issues

Calls Not Being Answered

Symptom: Incoming calls ring but are not answered by your assistant.

Possible Causes:

Phone number not registered in HMS Sovereign
No assistant assigned to the phone number
Assistant is set to is_active: false
SIP forwarding not configured correctly with your provider

Solution:

Verify the number is registered:

curl https://api.hmsovereign.com/api/v1/numbers \
  -H "Authorization: Bearer YOUR_API_KEY"

Check an assistant is assigned (assistant_id is not null)

Verify the assistant is active:

curl https://api.hmsovereign.com/api/v1/assistants/ASSISTANT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Contact your SIP provider to verify forwarding is configured

Calls Ending Immediately

Symptom: Calls connect but end within seconds.

Possible Causes:

Insufficient credits balance
BYOK API keys invalid or expired
LLM provider rate limiting

Solution:

Check your credits balance:

curl https://api.hmsovereign.com/api/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

Verify BYOK keys are valid by testing them directly with the provider
Check your provider dashboards for rate limit or billing issues

Poor Audio Quality

Symptom: Audio is choppy, delayed, or unclear.

Possible Causes:

Network latency between caller and our servers
TTS provider issues
STT provider struggling with audio input

Solution:

Check your network connectivity
Try a different TTS voice or provider
Ensure the caller's environment isn't too noisy

Webhook Issues

Webhooks Not Being Received

Symptom: Your endpoint isn't receiving webhook requests.

Possible Causes:

Incorrect webhook_url configured
Webhook events not enabled
Your endpoint is not accessible from the internet
Firewall blocking requests

Solution:

Verify webhook configuration:

curl https://api.hmsovereign.com/api/v1/assistants/ASSISTANT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Check webhook_url and webhook_events are set correctly

Test your endpoint is accessible:

curl -X POST https://your-domain.com/webhook \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

Check your firewall allows incoming POST requests

Webhook Signature Verification Failing

Symptom: Your signature verification always returns false.

Possible Causes:

Using wrong webhook_secret
Not using raw request body for verification
Timestamp format mismatch

Solution:

Verify you're using the correct secret from your assistant configuration

Use the raw request body (string), not parsed JSON:

# Correct
payload = request.get_data(as_text=True)

# Wrong
payload = json.dumps(request.json)  # This may reorder keys

Ensure timestamp is included in signature calculation

Assistant Request Timing Out

Symptom: Calls proceed with default configuration despite webhook being configured.

Cause: Your endpoint is taking more than 5 seconds to respond.

Solution:

Optimize your endpoint to respond faster
Cache frequently accessed data (CRM lookups, etc.)
Use async processing where possible
If you can't respond in time, return an empty object {} to use defaults

BYOK Issues

Provider Key Not Working

Symptom: Calls fail when using BYOK configuration.

Possible Causes:

API key is invalid or expired
Key doesn't have required permissions
Provider account has insufficient credits

Solution:

Test the key directly with the provider's API
Check key permissions (e.g., OpenAI keys need "All" access)
Verify provider account has available credits

Re-add the key via the BYOK API:

curl -X POST https://api.hmsovereign.com/api/v1/byok \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "api_key": "sk-..."}'

ElevenLabs Voices Not Working

Symptom: Assistant uses a different voice than configured.

Cause: The voice ID is not in your ElevenLabs Voice Library.

Solution:

Go to https://elevenlabs.io/app/voice-library
Add the voice you want to use to your library
Copy the voice ID from your library (not the public listing)
Update your assistant with the correct voice ID

Outbound Call Issues

402 Payment Required

Symptom: Outbound calls return 402 Payment Required.

Cause: Your organization has insufficient credits balance.

Solution: Add credits through the billing dashboard or API. See Billing Guide.

Outbound Call Not Connecting

Symptom: Outbound call initiated but destination never rings.

Possible Causes:

Invalid destination phone number format
Destination number is blocking unknown callers
SIP trunk configuration issue

Solution:

Verify phone number is in E.164 format (e.g., +31612345678)
Try calling a different test number
Check SIP trunk is configured for outbound calls

API Issues

429 Too Many Requests

Symptom: API returns 429 Too Many Requests.

Cause: You've exceeded the rate limit (100 requests/minute).

Solution:

Implement exponential backoff in your code
Check X-RateLimit-Remaining header to track usage
Cache responses where appropriate
Contact support if you need higher limits

400 Bad Request

Symptom: API returns 400 Bad Request with validation errors.

Solution: Read the error message carefully - it indicates which field is invalid:

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: phone_number",
    "param": "phone_number"
  }
}

Common validation issues:

Phone numbers must be E.164 format: +31612345678
UUIDs must be valid format
Required fields cannot be null

Getting Help

If you've tried the solutions above and still have issues:

Check the API response - Error messages often contain helpful details
Review recent changes - Did this work before? What changed?
Test with minimal configuration - Remove optional features to isolate the issue
Contact support - Email support@hmsovereign.com with:
- Your organization ID
- The request that's failing (redact sensitive data)
- The full error response
- Timestamp of when the issue occurred

On this page