This guide covers common issues you may encounter when integrating with Flireo and how to resolve them.Authentication Issues#
401 Unauthorized#
Symptom: All API requests return 401 Unauthorized.Missing Authorization header
1.
Verify your API key is correct
2.
Ensure the header format is Authorization: Bearer YOUR_API_KEY
3.
Check if the key is active in Settings > API Keys
4.
Generate a new key if needed
403 Forbidden#
Symptom: Request returns 403 Forbidden.Trying to access another organization's resources
Resource doesn't belong to your organization
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 agent.Phone number not registered in Flireo
No agent assigned to the phone number
Agent is set to is_active: false
SIP forwarding not configured correctly with your provider
1.
Verify the number is registered: 2.
Check an agent is assigned (agent_id is not null)
3.
Verify the agent is active: 4.
Contact your SIP provider to verify forwarding is configured
Insufficient credits balance
BYOK API keys invalid or expired
LLM provider rate limiting
1.
Check your credits balance: 2.
Verify BYOK keys are valid by testing them directly with the provider
3.
Check your provider dashboards for rate limit or billing issues
Poor Audio Quality#
Symptom: Audio is choppy, delayed, or unclear.Network latency between caller and our servers
STT provider struggling with audio input
1.
Check your network connectivity
2.
Try a different TTS voice or provider
3.
Ensure the caller's environment isn't too noisy
Webhook Issues#
Webhooks Not Being Received#
Symptom: Your endpoint isn't receiving webhook requests.Incorrect webhook_url configured
Webhook events not enabled
Your endpoint is not accessible from the internet
Firewall blocking requests
1.
Verify webhook configuration: 2.
Check webhook_url and webhook_events are set correctly
3.
Test your endpoint is accessible: 4.
Check your firewall allows incoming POST requests
Webhook Signature Verification Failing#
Symptom: Your signature verification always returns false.Using wrong webhook_secret
Not using raw request body for verification
Timestamp format mismatch
1.
Verify you're using the correct secret from your agent configuration
2.
Use the raw request body (string), not parsed JSON: 3.
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.1.
Optimize your endpoint to respond faster
2.
Cache frequently accessed data (CRM lookups, etc.)
3.
Use async processing where possible
4.
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.API key is invalid or expired
Key doesn't have required permissions
Provider account has insufficient credits
1.
Test the key directly with the provider's API
2.
Check key permissions (e.g., OpenAI keys need "All" access)
3.
Verify provider account has available credits
4.
Re-add the key via the BYOK API: ElevenLabs Voices Not Working#
Symptom: Agent uses a different voice than configured.Cause: The voice ID is not in your ElevenLabs Voice Library.2.
Add the voice you want to use to your library
3.
Copy the voice ID from your library (not the public listing)
4.
Update your agent 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.Invalid destination phone number format
Destination number is blocking unknown callers
SIP trunk configuration issue
1.
Verify phone number is in E.164 format (e.g., +31612345678)
2.
Try calling a different test number
3.
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).1.
Implement exponential backoff in your code
2.
Check X-RateLimit-Remaining header to track usage
3.
Cache responses where appropriate
4.
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"
}
}
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:1.
Check the API response - Error messages often contain helpful details
2.
Review recent changes - Did this work before? What changed?
3.
Test with minimal configuration - Remove optional features to isolate the issue
4.
The request that's failing (redact sensitive data)
Timestamp of when the issue occurred
Modified at 2025-12-31 12:10:00
