API Error Code Reference (iOS)
Note: This document is AI-generated based on the Confluence documentation "Telematics SDK Error Code Design".
This section maps each public iOS API to the specific error codes it can throw.
Common Errors (All APIs)
These errors can potentially occur in any API on both platforms:
| Error Code | Name | Scenario |
|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized before API call |
| 11010 | NETWORK_ERROR | Network connectivity issues (cloud mode) |
| 11011 | NETWORK_TIMEOUT | Network request timeout |
| 11050 | DATABASE_ERROR | Local database operation failed |
| 11040 | PARSE_JSON_FAILED | JSON parsing error |
| 32500 | SYSTEM_ERROR | Unexpected system error/exception |
SDK Initialization APIs
initialize()
Initialize the DriveMotion SDK.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11023 | SDK_ALREADY_INITIALIZED | SDK already initialized | Check initialization state before calling |
| 11026 | SDK_SHUTTING_DOWN | SDK is shutting down | Wait for shutdown to complete |
| 11021 | SDK_INITIALIZE_FAILED | SDK initialization failed with system error | Check logs, verify configuration |
| 32500 | SYSTEM_ERROR | System exception during initialization | Check logs, report issue |
shutdown()
Shutdown the DriveMotion SDK.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized | No action needed if already shutdown |
| 11024 | SDK_SHUTDOWN_NOT_INITIALIZED | SDK shutdown fail because not initialized | Check SDK state |
| 11025 | SDK_SHUTDOWN_SYSTEM_ERROR | Shutdown failed with system error | Check logs, report issue |
DriveMotion Client APIs (Trip Control)
getDriveDetectionState()
Get current drive detection state (AUTO_ON, AUTO_OFF, MANUAL_ON, MANUAL_OFF).
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized | Call initialize() first |
| 11035 | SDK_SETTING_NIL | SDK settings not defined | Check SDK initialization |
| 11301 | GET_DRIVE_DETECTION_STATE_FAIL | Could not get TNDataSourceCenter instance | Retry, check SDK state |
| 32500 | SYSTEM_ERROR | System exception | Check logs, report issue |
startDrive() / asynStartDrive()
Start manual trip recording session.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized (implicit) | Call initialize() first |
| 11002 | PERMISSION_NOT_DETERMINED | Location permission not determined | Request location permissions |
| 11003 | PERMISSION_RESTRICTED | Location permission restricted | Show settings prompt |
| 11004 | PERMISSION_DENIED | Location permission denied by user | Show settings prompt |
| 11006 | PERMISSION_UNKNOWN_STATUS | Unknown location authorization status | Check permission state |
| 11320 | AUTO_MODE_NOT_SUPPORT_START | DriveDetectionMode is AUTO | Use startDriveDetection() instead |
| 11340 | TRIP_ALREADY_STARTED | Trip already in progress | Call stopDrive() first or ignore |
| 11360 | START_TRIP_TIMEOUT | Start timeout (5 seconds) | Retry operation |
| 32500 | SYSTEM_ERROR | System exception (checkPermission or other) | Check logs, report issue |
stopDrive() / asynStopDrive()
Stop current trip recording session (Manual mode only).
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized (implicit) | Call initialize() first |
| 11321 | AUTO_MODE_NOT_SUPPORT_STOP | DriveDetectionMode is AUTO | Use stopDriveDetection() instead |
| 11341 | NO_LIVING_TRIP | No active trip to stop | Normal case, no action needed |
| 11361 | STOP_TRIP_TIMEOUT | Stop timeout (5 seconds) | Retry operation |
| 11050 | DATABASE_ERROR | Database query failed (getTripSummary) | Check DB integrity, retry |
| 32500 | SYSTEM_ERROR | System exception | Check logs, report issue |
startDriveDetection()
Start automatic trip detection (AUTO mode only).
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized | Call initialize() first |
| 11035 | SDK_SETTING_NIL | SDK settings undefined | Check SDK initialization |
| 11002 | PERMISSION_NOT_DETERMINED | Location permission not determined | Request location permissions |
| 11003 | PERMISSION_RESTRICTED | Location permission restricted | Show settings prompt |
| 11004 | PERMISSION_DENIED | Location permission denied by user | Show settings prompt |
| 11006 | PERMISSION_UNKNOWN_STATUS | Unknown location authorization status | Check permission state |
| 11322 | AUTO_MODE_REQUIRED_FOR_START_DETECTION | Called in MANUAL mode | Use startDrive() instead |
| 11330 | NOT_OPT_IN_FOR_START_DETECTION | User not opted in (when optInRequired=true) | Call optIn() first |
| 32500 | SYSTEM_ERROR | System exception (checkPermission or other) | Check logs, report issue |
stopDriveDetection()
Stop automatic trip detection (can be called in any mode).
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized | Call initialize() first |
Note: This API has minimal error handling. It only checks if SDK is initialized, then stops trip detection regardless of current mode.
User Client APIs (User Management)
getUserProfile()
Retrieve user profile information.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized | Call initialize() first |
| 11101 | GET_USER_PROFILE_FAIL | Cloud request failed | Retry, check network |
| 11010 | NETWORK_ERROR | Network connectivity issue | Check connection, retry |
| 11011 | NETWORK_TIMEOUT | Request timeout | Retry with longer timeout |
optIn() / optOut()
User opt-in/out for data collection.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized | Call initialize() first |
| 11122/11123 | OPT_IN/OUT_NOT_SUPPORT | optInRequired is false | Feature not enabled in config |
| 11104 | USER_PROFILE_NOT_FOUND | No user profile exists | Create user profile first |
| 11120/11121 | OPT_IN/OUT_REQUEST_FAIL | Create request failed | Retry operation |
| 11010 | NETWORK_ERROR | Network connectivity issue | Check connection, retry |
| 11040 | PARSE_JSON_FAILED | Parse response failed | Check server response |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |
deleteAccountAndData()
Delete user account and all associated data, then shutdown SDK.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized or no user profile | Call initialize() first |
| 11105 | DELETE_ACCOUNT_REQUEST_FAIL | Delete account network request failed | Retry operation |
| 11024 | SDK_SHUTDOWN_NOT_INITIALIZED | SDK shutdown failed (not initialized) | Check SDK state |
| 11025 | SDK_SHUTDOWN_SYSTEM_ERROR | SDK shutdown failed (system error) | Check logs, report issue |
| 11010 | NETWORK_ERROR | Network connectivity issue | Check connection, retry |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |
Analytics Client APIs (Trip & Score Data)
getTrips()
Get trip history with optional filters.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized (implicit) | Call initialize() first |
| 11041 | USER_ID_OR_ASSET_ID_MISSING | User ID or Asset ID missing | Provide valid user/asset ID |
| 11230 | NO_TRIPS | No trips match criteria | Normal case, show empty state |
| 11062 | UNSUPPORT_CONNECTION_MODE | Invalid connection mode | Check connection mode setting |
| 11040 | PARSE_JSON_FAILED | JSON decode failed (cloud) | Report to backend team |
| 11010 | NETWORK_ERROR | Network error (cloud mode) | Check connection, retry |
| 11050 | DATABASE_ERROR | Database query failed | Check DB integrity |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |
getTripDetail()
Get detailed trip information including events and locations.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized (implicit) | Call initialize() first |
| 11530 | GET_CHANNEL_CLIENT_ID_FAIL | Cannot find channel client ID (cloud mode) | Provide valid VIN/asset ID |
| 11232 | TRIP_NOT_FOUND | Trip ID doesn't exist (returns nil) | Show "Trip not found" message |
| 11237 | GET_TRIP_DETAIL_FAIL | Get trip detail fail | Retry operation, check network |
| 11062 | UNSUPPORT_CONNECTION_MODE | Invalid connection mode | Check connection mode setting |
| 11040 | PARSE_JSON_FAILED | JSON decode failed (cloud) | Report to backend team |
| 11010 | NETWORK_ERROR | Network error (cloud mode) | Check connection, retry |
| 11050 | DATABASE_ERROR | Database query failed | Check DB integrity |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |
getLatestTripDetail()
Get most recent trip detail.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized (implicit) | Call initialize() first |
| 11041 | USER_ID_OR_ASSET_ID_MISSING | User ID or Asset ID missing | Provide valid user/asset ID |
| 11230 | NO_TRIPS | No trips available (returns nil) | Show "No trips yet" message |
| 11232 | TRIP_NOT_FOUND | Latest trip not found (returns nil) | Show empty state |
| 11062 | UNSUPPORT_CONNECTION_MODE | Cloud mode not supported | Use default mode only |
| 11050 | DATABASE_ERROR | Database query failed | Check DB integrity |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |
getLiveTripDetail()
Get current ongoing trip detail.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized (implicit) | Call initialize() first |
| 11230 | NO_TRIPS | No active trip (returns nil) | Show "No active trip" message |
| 11062 | UNSUPPORT_CONNECTION_MODE | Cloud mode not supported | Use default mode only |
| 11050 | DATABASE_ERROR | Database query failed | Check DB integrity |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |
getTripsByIds()
Get multiple trips by their IDs.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized (implicit) | Call initialize() first |
| 11234 | GET_TRIPS_BY_IDS_NO_DATA | No data received for get trips by ids | Check trip IDs validity |
| 11235 | GET_TRIPS_BY_IDS_REQUEST_FAILED | Get trips by ids request failed | Retry operation, check network |
| 11236 | GET_TRIPS_BY_IDS_DECODE_FAILED | Failed to decode get trips by ids response | Report to backend team |
| 11062 | UNSUPPORT_CONNECTION_MODE | Invalid connection mode | Check connection mode setting |
| 11040 | PARSE_JSON_FAILED | JSON decode failed (cloud) | Report to backend team |
| 11010 | NETWORK_ERROR | Network error (cloud mode) | Check connection, retry |
| 11050 | DATABASE_ERROR | Database query failed | Check DB integrity |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |
updateTripTransportationMode()
Update trip's transportation mode (car/bike/walk/etc).
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized (implicit) | Call initialize() first |
| 11232 | TRIP_NOT_FOUND | Trip ID doesn't exist | Show "Trip not found" |
| 11250 | VEHICLE_MODE_CANNOT_CHANGE | Trip is vehicle type | Show "Cannot change vehicle mode" |
| 11050 | DATABASE_ERROR | Database operation failed | Retry operation |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |
syncTrips()
Sync trips from cloud to local database.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized (implicit) | Call initialize() first |
| 11233 | SYNC_TRIPS_FAIL | Sync operation failed | Retry operation |
| 11010 | NETWORK_ERROR | Network error | Check connection, retry |
| 11050 | DATABASE_ERROR | Database operation failed | Check DB integrity |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |
getCumulativeSafetyScore()
Get cumulative safety score for a time period.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized (implicit) | Call initialize() first |
| 11201 | GET_CUMULATIVE_SAFETY_SCORE_FAIL | Get cumulative safety score fail | Show "Score unavailable" |
| 11050 | DATABASE_ERROR | Database query failed | Check DB integrity |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |
getSimulatedSafetyScore()
Get simulated safety score.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized (implicit) | Call initialize() first |
| 11202 | GET_SIMULATED_SAFETY_SCORE_FAIL | Get simulated safety score fail | Show "Score unavailable" |
| 11010 | NETWORK_ERROR | Network error (cloud mode) | Check connection, retry |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |
aggregatedSafetyScore()
Get aggregated safety score (cloud only).
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized (implicit) | Call initialize() first |
| 11010 | NETWORK_ERROR | Network error | Check connection, retry |
| 11040 | PARSE_JSON_FAILED | JSON decode failed | Report to backend team |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |
getStreaks()
Get driving streaks data.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized (implicit) | Call initialize() first |
| 11050 | DATABASE_ERROR | Database query failed | Check DB integrity |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |
getEventPercentileTable()
Get event percentile table for scoring.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized (implicit) | Call initialize() first |
| 11040 | PARSE_JSON_FAILED | Config parse failed | Check config file |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |
getConfigDescriptions()
Get configuration descriptions.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized (implicit) | Call initialize() first |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |
postContextualCoaching()
Post contextual coaching request.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized (implicit) | Call initialize() first |
| 11370 | CONTEXTUAL_COACHING_CALCULATE_SCORE_FAILED | Failed to calculate contextual coaching score | Check trip data availability |
| 11371 | CONTEXTUAL_COACHING_TRIPS_EMPTY | Trips are empty for contextual coaching | Ensure trips exist before requesting |
| 11372 | CONTEXTUAL_COACHING_SCORE_SERVICE_NIL | Safety score service returned nil for contextual coaching | Check SDK initialization and score service |
| 11373 | CONTEXTUAL_COACHING_NO_TRIPS_FOUND | No trips found for contextual coaching | Ensure trips exist in the specified time range |
| 11010 | NETWORK_ERROR | Network error | Check connection, retry |
| 11040 | PARSE_JSON_FAILED | JSON decode failed | Report to backend team |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |
getContextualCoaching()
Get contextual coaching data by coaching ID.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized (implicit) | Call initialize() first |
| 11370 | CONTEXTUAL_COACHING_CALCULATE_SCORE_FAILED | Failed to calculate contextual coaching score | Check trip data availability |
| 11371 | CONTEXTUAL_COACHING_TRIPS_EMPTY | Trips are empty for contextual coaching | Ensure trips exist before requesting |
| 11372 | CONTEXTUAL_COACHING_SCORE_SERVICE_NIL | Safety score service returned nil for contextual coaching | Check SDK initialization and score service |
| 11373 | CONTEXTUAL_COACHING_NO_TRIPS_FOUND | No trips found for contextual coaching | Ensure trips exist in the specified time range |
| 11010 | NETWORK_ERROR | Network error | Check connection, retry |
| 11040 | PARSE_JSON_FAILED | JSON decode failed | Report to backend team |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |
getContextualCoachingStatistics() (Deprecated)
Get contextual coaching statistics (edge-side API, will be removed).
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized (implicit) | Call initialize() first |
| 11050 | DATABASE_ERROR | Database query failed | Check DB integrity |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |
Note: This API is deprecated and will be removed in future versions. Use cloud APIs instead
Enrollment Client APIs (Vehicle/Peripheral Management)
getEnrollmentStatus()
Get vehicle enrollment status for given VINs.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized | Call initialize() first |
| 11010 | NETWORK_ERROR | Network error | Check connection, retry |
| 11040 | PARSE_JSON_FAILED | JSON decode failed | Report to backend team |
getRecommendedPeripherals()
Get recommended Bluetooth peripherals for vehicle connection.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized | Call initialize() first |
| 11010 | NETWORK_ERROR | Network error | Check connection, retry |
| 11040 | PARSE_JSON_FAILED | JSON decode failed | Report to backend team |
launchAuthFlow()
Launch third-party authorization flow (e.g., Smartcar) to connect vehicle.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized | Call initialize() first |
| 11520 | LAUNCH_AUTH_FLOW_VIN_EMPTY | VIN is empty | Provide valid VIN |
| 11521 | LAUNCH_AUTH_FLOW_VC_EMPTY | ViewController is nil | Provide valid view controller |
| 32500 | SYSTEM_ERROR | Auth flow error | Check logs, report issue |
linkVehicleToPeripheral()
Link a Bluetooth peripheral to a vehicle.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized or no user profile | Call initialize() and ensure user logged in |
| 11530 | GET_CHANNEL_CLIENT_ID_FAIL | Failed to get channel client ID | Check VIN/assetId, refresh user profile |
| 11531 | PERIPHERAL_ADDRESS_EMPTY | Peripheral address is empty | Provide valid peripheral address |
| 11010 | NETWORK_ERROR | Network error | Check connection, retry |
| 32500 | SYSTEM_ERROR | Link operation failed | Check logs, report issue |
replaceVehiclePeripheral()
Replace an existing peripheral with a new one for a vehicle.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized | Call initialize() first |
| 11530 | GET_CHANNEL_CLIENT_ID_FAIL | Failed to get channel client ID | Check VIN/assetId |
| 11531 | PERIPHERAL_ADDRESS_EMPTY | Current peripheral address empty | Provide valid current peripheral |
| 11531 | PERIPHERAL_ADDRESS_EMPTY | New peripheral address empty | Provide valid new peripheral |
| 11010 | NETWORK_ERROR | Network error | Check connection, retry |
| 32500 | SYSTEM_ERROR | Replace operation failed | Check logs, report issue |
migratePeripherals()
Automatically migrate peripheral connections across vehicles.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized or settings missing | Call initialize() first |
| 11550 | EDGE_MATCHER_NOT_ENABLED | isEdgeMatcherEnabled is false | Enable edge matcher in settings |
| 11551 | MIGRATE_PERIPHERALS_FAIL | Migrate peripherals fail | Check network connection and retry |
| 11552 | MIGRATE_PERIPHERALS_FETCH_CONNECTIONS_FAILED | Failed to fetch connections for migration | Check network connection, retry operation |
| 11553 | MIGRATE_PERIPHERALS_VEHICLE_PROFILES_NOT_FOUND | Vehicle profiles not found for migration | Ensure vehicle profiles exist before migration |
| 11554 | MIGRATE_PERIPHERALS_MISSING_CHANNEL_CLIENT_ID | Missing channel client ID for migration | Check VIN/assetId, refresh user profile |
| 11555 | MIGRATE_PERIPHERALS_REQUEST_FAIL | Migration request failed | Check network connection, retry operation |
| 32500 | SYSTEM_ERROR | Migration failed | Check logs, report issue |