> ## Documentation Index
> Fetch the complete documentation index at: https://www.vobiz.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and troubleshooting in the Vobiz Flutter SDK

> Every exception the Vobiz Flutter SDK throws, every errorEvents code, the access-token error codes 10001 to 10010, common SIP codes on failed calls, and fixes for the most frequent problems.

The SDK reports problems in two ways:

* **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`](https://www.vobiz.ai/docs/integrations/flutter-sdk/conference) instead. |

```dart theme={null}
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](https://www.vobiz.ai/docs/integrations/flutter-sdk/network.md#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](#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](https://www.vobiz.ai/docs/integrations/flutter-sdk/sign-in.md#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. |

For the carrier's own response, look up the call in your [call detail records](https://www.vobiz.ai/docs/cdr.md).

## 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](https://www.vobiz.ai/docs/platform/voice/applications.md) 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](https://www.vobiz.ai/docs/integrations/flutter-sdk/push-notifications.md) (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](https://www.vobiz.ai/docs/integrations/flutter-sdk/network.md#stun-and-turn). |
| 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. |

Turn on `SdkConfig(debug: true)` to see the SDK's log, including the first line of every SIP request and response.

## Next steps

* [Events and states](https://www.vobiz.ai/docs/integrations/flutter-sdk/events.md)
* [Sign in](https://www.vobiz.ai/docs/integrations/flutter-sdk/sign-in.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.