Error Codes
This reference documents all error codes and messages returned by the SFVoPI API.
Authentication Errors
401 Unauthorized
| Message | Cause | Fix |
|---|---|---|
UnAuthorized, Please Login | User session not found or expired | Log in again with valid credentials |
UnAuthorized, Please Login to Organisation | Organization session not found | Select an organization after login |
UnAuthorized, Please Provide API Key | Missing x-api-key header in request | Include x-api-key header with valid API key |
UnAuthorized, Please Provide Valid API Key | API key is invalid or revoked | Verify API key is correct and active |
UnAuthorized | Generic authentication failure | Check credentials and session status |
tip
Always include the x-api-key header for API requests. Session-based auth requires valid login.
App Management Errors
404 Not Found
| Message | Cause | Fix |
|---|---|---|
SFVoPI app not found | App ID does not exist or belongs to different org | Verify app ID and organization ownership |
500 Internal Server Error
| Message | Cause | Fix |
|---|---|---|
Failed to create SFVoPI app: {error} | Server error during app creation | Check request payload and retry |
Failed to get SFVoPI apps: {error} | Server error retrieving apps | Retry request or contact support |
Failed to get SFVoPI app: {error} | Server error retrieving specific app | Verify app exists and retry |
Failed to update SFVoPI app: {error} | Server error during update | Check request payload and retry |
Failed to delete SFVoPI app: {error} | Server error during deletion | Verify app exists and retry |
Number Management Errors
400 Bad Request
| Message | Cause | Fix |
|---|---|---|
VoIP number not found or does not belong to this org | Number doesn't exist or belongs to different org | Verify number ownership and organization |
404 Not Found
| Message | Cause | Fix |
|---|---|---|
SFVoPI app not found | App ID does not exist | Verify app ID is correct |
Number not linked to this app | Number is not associated with the app | Link number to app first |
409 Conflict
| Message | Cause | Fix |
|---|---|---|
VoIP number is already linked to another SFVoPI app | Number is already linked to different app | Unlink from previous app first |
500 Internal Server Error
| Message | Cause | Fix |
|---|---|---|
Failed to link number: {error} | Server error during linking | Verify number and app exist, retry |
Failed to unlink number: {error} | Server error during unlinking | Verify link exists and retry |
Failed to get numbers: {error} | Server error retrieving numbers | Retry request or contact support |
Failed to get available numbers: {error} | Server error retrieving available numbers | Retry request or contact support |
Failed to get app by number: {error} | Server error looking up app | Retry request or contact support |
Call Errors
400 Bad Request
| Message | Cause | Fix |
|---|---|---|
VoIP number {number} is not linked to any SFVoPI app for this org | Source number not linked to active app | Link number to app with ACTIVE status |
500 Internal Server Error
| Message | Cause | Fix |
|---|---|---|
Service temporarily unavailable | Superfone service is temporarily unavailable | Check service status and retry |
Failed to initiate outbound call | Call could not be placed at this time | Retry after a few seconds or contact support |
Failed to initiate outbound call: {error} | General error during call initiation | Check request payload and retry |
Webhook Errors
502 Bad Gateway
| Message | Cause | Fix |
|---|---|---|
Both answer_url and fallback_answer_url failed | Both webhook URLs failed to respond | Verify webhook endpoints are accessible and responding |
Webhook response failed schema validation | Webhook response doesn't match expected format | Return valid stream response JSON |
answer_url timeout | Webhook URL took too long to respond | Optimize webhook handler or increase timeout |
answer_url returned HTTP {status} | Webhook URL returned error status | Check webhook implementation and fix errors |
answer_url connection failed: {error} | Cannot connect to webhook URL | Verify URL is accessible and firewall allows connections |
Invalid webhook response from answer_url | Webhook response is malformed | Return valid JSON response |
info
Webhook URLs must respond within 10 seconds. Implement fallback_answer_url for reliability.
Best Practices
Error Handling
- Always check HTTP status codes - 4xx errors are client issues, 5xx are server issues
- Implement exponential backoff - Retry 5xx errors with increasing delays
- Log error messages - Store error details for debugging and monitoring
- Use fallback URLs - Configure fallback_answer_url for webhook reliability
Common Issues
| Issue | Solution |
|---|---|
| 401 errors on API calls | Verify API key is included in x-api-key header |
| 404 app not found | Check app ID and ensure it belongs to your organization |
| 409 number already linked | Unlink number from previous app before linking to new one |
| 502 webhook errors | Ensure webhook URL is publicly accessible and responds within 10 seconds |
| Outbound calls fail | Verify source number is linked to active app and provider is configured |
tip
Enable detailed logging in your webhook handlers to quickly identify and fix integration issues.