- Exceptions from the method you called, for mistakes you can fix in code, such as a missing argument or calling with no call in progress.
- Error events on
client.errorEvents, for things that fail later or in the background, such as a refused registration or a dropped network.
Exceptions
| Exception | Thrown when |
|---|---|
ArgumentError | An argument is invalid: an empty destination, a malformed caller ID, invalid SIP headers, bad DTMF digits, or a token for another user. The message says what to fix. |
StateError | The client isn’t in the right state: not registered, offline, already in a call, no connected call to hold, or no access-token sign-in to update. |
VobizException | A request to Vobiz or your backend failed. Has code, message, statusCode, and cause. |
VobizDemoModeRequiredException | A demo-only method was called without SdkConfig(unsafeDemoZeroConfig: true). Code demo_mode_required. |
VobizCredentialsException | A credentials provider failed or returned empty credentials. Code credentials_failed. |
VobizRegistrationException | A credentials session gave up after repeated refusals. Reported on session.failures. |
VobizAccessTokenException | An access token couldn’t be used. Code access_token_failed, with tokenError (10001 to 10010) and tokenErrorName. |
UnsupportedError | A legacy call-control method (transfer, addCall, swapCalls, and similar) was called against a server that doesn’t implement it. Use transferCall or VobizConference instead. |
Future<void> safeCall(VobizClient client) async {
try {
await client.makeCall('+91XXXXXXXXXX', callerId: '+91YYYYYYYYYY');
} on VobizAccessTokenException catch (e) {
debugPrint('Token problem ${e.tokenError} ${e.tokenErrorName}: ${e.message}');
} on VobizException catch (e) {
debugPrint('Vobiz error ${e.code}: ${e.message}');
} on ArgumentError catch (e) {
debugPrint('Invalid input: ${e.message}');
} on StateError catch (e) {
debugPrint('Not now: ${e.message}');
}
}
Error codes
ErrorEvent.code, and VobizException.code where it applies. Codes with a constant are on VobizErrorCode.
| Code | Constant | When |
|---|---|---|
connect_failed | connectFailed | The WebSocket to the registrar couldn’t be opened. With autoReconnect, the SDK retries. |
registration_failed | registrationFailed | Vobiz refused the REGISTER: wrong credentials (403), or a refused access token (the cause is a VobizAccessTokenException). |
socket_error | socketError | The connection dropped unexpectedly. |
reconnect_failed | Reconnecting gave up after the reconnect policy’s attempts. Call client.reconnect() to try again. | |
make_call_failed | makeCallFailed | An outbound call couldn’t start, for example the microphone couldn’t be opened. |
call_failed | callFailed | Vobiz or the far end refused the call. See the CallEvent’s sipCode. |
auth_failed | authFailed | A call request was refused with 401 or 407. |
call_timeout | callTimeout | Vobiz didn’t answer the call request within 30 seconds. |
answer_failed | answerFailed | An incoming call couldn’t be answered, or the far end’s answer couldn’t be used. |
network_lost | The network dropped during a call and didn’t come back within 12 seconds. | |
hold_failed / resume_failed | The far end refused hold or resume. The call carries on as it was. | |
access_token_failed | accessTokenFailed | An access token couldn’t be used. See Access-token errors. |
credentials_failed | credentialsFailed | A credentials provider failed. |
conference_failed | conferenceFailed | Your conference server refused a request. |
push_device_failed | Vobiz refused a push-device registration or logout. | |
demo_mode_required | demoModeRequired | A demo-only method was called without demo mode. |
setup_failed | setupFailed | Demo mode: Zero-Config couldn’t provision the endpoint. |
transfer_failed | transferFailed | Demo mode: the transfer was refused. |
recordings_failed | recordingsFailed | Demo mode: the recordings list couldn’t be read. |
backend_failed | A legacy call-control route on the webhook server failed. |
Access-token errors
When the registrar refuses an access token,VobizAccessTokenException.tokenError holds its reason:
| Code | Name | Meaning | Fix |
|---|---|---|---|
| 10001 | INVALID_ACCESS_TOKEN | Not a JWT, or a claim is missing or has the wrong type. Also raised by the SDK before connecting. | Mint the token with every required claim, including app. |
| 10002 | INVALID_ACCESS_TOKEN_HEADER | The JWT header isn’t one Vobiz signs. | Mint tokens with Vobiz’s token API. |
| 10003 | INVALID_ACCESS_TOKEN_ISSUER | iss isn’t a known Auth ID. | Set iss to your Auth ID. |
| 10004 | INVALID_ACCESS_TOKEN_SUBJECT | sub names no identity on that account. | Check the user ID you put in sub. |
| 10005 | ACCESS_TOKEN_NOT_VALID_YET | nbf is still in the future. | Set nbf about 60 seconds in the past. The token provider retries this one after 3 seconds. |
| 10006 | ACCESS_TOKEN_EXPIRED | exp has passed. | Renew before expiry with a token provider or updateAccessToken. |
| 10007 | INVALID_ACCESS_TOKEN_SIGNATURE | The signature doesn’t match your account. | Mint the token on your backend with your current Auth Token. |
| 10008 | INVALID_ACCESS_TOKEN_GRANTS | per.voice doesn’t allow this action, such as an outgoing call without outgoing_allow. | Grant the permission when you mint the token. |
| 10009 | EXPIRATION_EXCEEDS_MAX_ALLOWED_TIME | exp - nbf is outside 180 seconds to 24 hours. | Mint a token with a lifetime in that range. |
| 10010 | MAX_ALLOWED_LOGIN_REACHED | Too many sign-ins for this identity. | Sign out unused sessions, or give each device its own sub. |
VobizAccessTokenException.errorName(code) returns the name for a code.
SIP codes on failed calls
When a call fails,CallEvent.sipCode holds the SIP status and reason the far end’s explanation.
| Code | Usual meaning |
|---|---|
| 403 | Forbidden: for example, a caller ID your account doesn’t own, or a destination you’re not allowed to call. |
| 404 | Not found: the number or SIP user doesn’t exist, or the SIP user isn’t registered. |
| 408 | No answer to the request in time. |
| 480 | Temporarily unavailable: the called user can’t take calls right now. |
| 486 | Busy. Vobiz also reports some carrier failures as busy. |
| 487 | The call was cancelled before it was answered. |
| 488 | No common audio format. |
| 500 | A server-side failure. For calls from an endpoint, check that the endpoint has an application attached. |
| 503 | Service unavailable, for example your account’s capacity limit was reached. |
| 603 | Declined by the called person. |
Troubleshooting
| Problem | Likely cause and fix |
|---|---|
registration_failed with “Wrong credentials” | The username or password is wrong. Use the full SIP username from Voice > Endpoints (Vobiz adds digits to the one you typed). |
| Every outbound call fails at once | The endpoint has no application, so Vobiz has no Answer URL to ask. Attach an application to the endpoint. |
| Calls to phones fail, calls to SIP users work | The caller ID isn’t a number your account owns. Set <Dial callerId="..."> to one of your numbers. |
| The app never rings | It isn’t registered, or another device signed in with the same SIP username: only the newest registration rings. Check that client.isConnected is true. |
| The app rings in the foreground but not when closed | Set up Vobiz push (Android). iOS rings only while the app is open. |
| The call connects but nobody hears anything | Microphone permission denied, an emulator without host audio, or a network that blocks the audio path: add a TURN server. |
| Audio stops after switching Wi-Fi to mobile | Expected for up to a few seconds while the call recovers. If it lasts over 12 seconds, the call ends with network_lost. |
| The headset isn’t used | BLUETOOTH_CONNECT isn’t granted (Android 12 and later). |
reconnect_failed | Reconnecting gave up. Call client.reconnect(), or set ReconnectPolicy(maxAttempts: null). |
| A brand-new access token is refused with 10005 | The registrar’s clock is behind your server’s. Set nbf 60 seconds in the past. |
SdkConfig(debug: true) to see the SDK’s log, including the first line of every SIP request and response.