API Error Code Reference (Android)
Note: This document is AI-generated based on the Confluence documentation "Telematics SDK Error Code Design".
This section maps each public Android API to the specific error codes it can throw, based on actual implementation analysis.
Common Errors (All APIs)
These errors can potentially occur in any API:
| 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
DriveMotionService.initialize()
Initialize the DriveMotion SDK (both sync and async versions).
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 |
| 11022 | SDK_INITIALIZING | SDK initialization in progress (async only) | Wait for current initialization 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 |
DriveMotionService.initializeDataConnector()
Initialize DataConnector in advance before SDK initialization.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11073 | DATA_CONNECTOR_INIT_WHEN_SDK_INITIALIZING | Cannot initialize while SDK is initializing | Wait for SDK initialization to complete |
| 11072 | DATA_CONNECTOR_EXTERNAL_INIT_FORBIDDEN | External init not allowed after SDK initialized | Call before SDK initialization |
| 11071 | DATA_CONNECTOR_INITIALIZE_FAILED | DataConnector initialization failed | Check logs, verify settings |
DriveMotionService.shutdown()
Shutdown the DriveMotion SDK (both sync and async versions).
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11020 | SDK_NOT_INITIALIZED | SDK not initialized | No action needed if already shutdown |
| 11026 | SDK_SHUTTING_DOWN | SDK shutdown in progress (async only) | Wait for current shutdown to complete |
| 11022 | SDK_INITIALIZING | SDK still initializing | Wait for initialization to complete first |
| 11025 | SDK_SHUTDOWN_SYSTEM_ERROR | Shutdown failed with system error | Check logs, report issue |
DriveMotion Client APIs (Trip Control)
startDriveRequest() / startDrive()
Start manual trip recording session.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11311 | MANUAL_MODE_REQUIRED_FOR_START | DriveDetectionMode is AUTO | Use startDriveDetectionRequest() instead |
| 11340 | TRIP_ALREADY_STARTED | Trip already in progress | Call stopDriveRequest() first or ignore |
| 11360 | START_TRIP_TIMEOUT | Start timeout (10 seconds) | Retry operation |
| 32500 | SYSTEM_ERROR | System exception | Check logs, report issue |
Note: Permission checking is handled by DataConnector service internally.
stopDriveRequest() / stopDrive()
Stop current trip recording session (Manual mode only).
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11312 | MANUAL_MODE_REQUIRED_FOR_STOP | DriveDetectionMode is AUTO | Use stopDriveDetectionRequest() instead |
| 11361 | STOP_TRIP_TIMEOUT | Stop timeout (10 seconds) | Retry operation |
| 32500 | SYSTEM_ERROR | System exception | Check logs, report issue |
startDriveDetectionRequest()
Start automatic trip detection (AUTO mode only).
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11305 | INVALID_DRIVE_DETECTION_MODE | Called in MANUAL mode | Use startDriveRequest() instead |
| 11124 | USER_NOT_OPT_IN | User not opted in (when optInRequired=true) | Call optInRequest() first |
| 11104 | USER_PROFILE_NOT_FOUND | User profile not found when checking consent | Call getUserProfileRequest() first |
| 32500 | SYSTEM_ERROR | System exception | Check logs, report issue |
stopDriveDetectionRequest()
Stop automatic trip detection (can be called in any mode).
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 32500 | SYSTEM_ERROR | System exception | Check logs, report issue |
Note: This API has minimal error handling. It stops trip detection regardless of current mode.
getDriveDetectionStateRequest()
Get current drive detection state.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 32500 | SYSTEM_ERROR | System exception | Check logs, report issue |
User Client APIs (User Management)
getUserProfileRequest()
Retrieve user profile information.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11010 | NETWORK_ERROR | Network connectivity issue | Check connection, retry |
| 11011 | NETWORK_TIMEOUT | Request timeout | Retry with longer timeout |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |
optInRequest() / optOutRequest()
User opt-in/out for data collection.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 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 |
| 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 |
deleteAccountAndDataRequest()
Delete user account and all associated data, then shutdown SDK.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11010 | NETWORK_ERROR | Network connectivity issue | Check connection, retry |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |
Note: This API automatically calls shutdown() after successful deletion.
Analytics Client APIs (Trip & Score Data)
getTripsRequest()
Get trip history with optional filters.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11041 | USER_ID_OR_ASSET_ID_MISSING | User ID or Asset ID missing | Provide valid user/asset ID |
| 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 |
getTripDetailRequest()
Get detailed trip information including events and locations.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11041 | USER_ID_OR_ASSET_ID_MISSING | Cannot find channel client ID (cloud mode) | Provide valid VIN/asset ID |
| 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 |
getLatestTripDetailRequest()
Get most recent trip detail.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11062 | UNSUPPORT_CONNECTION_MODE | Cloud mode not supported | Use default mode only |
| 11041 | USER_ID_OR_ASSET_ID_MISSING | User ID or Asset ID missing | Provide valid user/asset ID |
| 11230 | NO_TRIPS | No trips available | Show "No trips yet" message |
| 11050 | DATABASE_ERROR | Database query failed | Check DB integrity |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |
getLiveTripDetailRequest()
Get current ongoing trip detail.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11050 | DATABASE_ERROR | Database query failed | Check DB integrity |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |
Note: Returns null for liveTrip if no active trip exists (not an error).
getTripsByIdsRequest()
Get multiple trips by their IDs.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 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 |
updateTripTransportationModeRequest()
Update trip's transportation mode (car/bike/walk/etc).
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11231 | 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 |
syncTripsRequest()
Sync trips from cloud to local database.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11238 | SYNC_TRIPS_IN_PROGRESS | Sync already in progress | Wait for current sync to complete |
| 11240 | SYNC_TRIPS_NETWORK_FORBIDDEN | Network request forbidden | Check network settings |
| 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 |
getCumulativeSafetyScoreRequest()
Get cumulative safety score for a time period.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11210 | INVALID_SCORE_VERSION | Invalid score version parameter | Use valid score version |
| 11211 | CUMULATIVE_SCORE_NOT_EXIST | Score not exist for given parameters | Check time range and parameters |
| 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 |
getSimulatedSafetyScoreRequest()
Get simulated safety score.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11210 | INVALID_SCORE_VERSION | Invalid score version parameter | Use valid score version |
| 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 |
aggregatedSafetyScoreRequest()
Get aggregated safety score (cloud only).
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 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 |
getStreaksRequest()
Get driving streaks data.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11050 | DATABASE_ERROR | Database query failed | Check DB integrity |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |
Enrollment Client APIs (Vehicle/Peripheral Management)
getEnrollmentStatusRequest()
Get vehicle enrollment status for given VINs.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 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 |
getRecommendedPeripheralsRequest()
Get recommended Bluetooth peripherals for vehicle connection.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 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 |
launchAuthFlowRequest()
Launch third-party authorization flow (e.g., Smartcar) to connect vehicle.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11520 | LAUNCH_AUTH_FLOW_VIN_EMPTY | VIN is empty | Provide valid VIN |
| 11523 | ENROLLMENT_VIN_MISSING | VIN parameter missing | Provide valid VIN |
| 11524 | ENROLLMENT_CONFIG_NOT_FOUND | Config not found for VIN | Check VIN validity |
| 11525 | ENROLLMENT_AUTH_CODE_EMPTY | Authorization code empty | Check auth flow response |
| 11526 | ENROLLMENT_EXCHANGE_AUTH_CODE_FAILED | Code exchange failed | Retry auth flow |
| 32500 | SYSTEM_ERROR | Auth flow error | Check logs, report issue |
linkVehicleToPeripheralRequest()
Link a Bluetooth peripheral to a vehicle.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11550 | EDGE_MATCHER_NOT_ENABLED | isEdgeMatcherEnabled is false | Enable edge matcher in settings |
| 11540 | ENROLLMENT_TELEMATICS_USER_ID_MISSING | Cannot get telematics user ID | Check user authentication |
| 11541 | ENROLLMENT_CHANNEL_CLIENT_ID_NOT_FOUND | Cannot find channel client ID | Refresh user profile, check VIN/assetId |
| 11542 | ENROLLMENT_PHONE_DEVICE_GUID_MISSING | Cannot get phone's device GUID | Check device settings |
| 11531 | PERIPHERAL_ADDRESS_EMPTY | Peripheral address is empty | Provide valid peripheral address |
| 11543 | ENROLLMENT_UPDATE_CONNECTION_FAILED | Failed to update peripheral connection | Check network, retry |
| 11010 | NETWORK_ERROR | Network error | Check connection, retry |
| 32500 | SYSTEM_ERROR | Link operation failed | Check logs, report issue |
replaceVehiclePeripheralRequest()
Replace an existing peripheral with a new one for a vehicle.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11550 | EDGE_MATCHER_NOT_ENABLED | isEdgeMatcherEnabled is false | Enable edge matcher in settings |
| 11540 | ENROLLMENT_TELEMATICS_USER_ID_MISSING | Cannot get telematics user ID | Check user authentication |
| 11541 | ENROLLMENT_CHANNEL_CLIENT_ID_NOT_FOUND | Cannot find channel client ID | Check VIN/assetId |
| 11531 | PERIPHERAL_ADDRESS_EMPTY | Current or new peripheral address empty | Provide valid peripheral addresses |
| 11543 | ENROLLMENT_UPDATE_CONNECTION_FAILED | Failed to update connection | Check network, retry |
| 11010 | NETWORK_ERROR | Network error | Check connection, retry |
| 32500 | SYSTEM_ERROR | Replace operation failed | Check logs, report issue |
migratePeripheralsRequest()
Automatically migrate peripheral connections across vehicles.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 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 |
| 11010 | NETWORK_ERROR | Network error | Check connection, retry |
| 32500 | SYSTEM_ERROR | Migration failed | Check logs, report issue |
Monitor Client APIs
getUploadProgressRequest()
Get upload progress information.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11401 | GET_UPLOAD_PROGRESS_FAIL | Failed to get upload progress | Retry operation |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |
getUploadTimestampRequest()
Get upload timestamp information.
Possible Error Codes:
| Error Code | Name | Scenario | How to Handle |
|---|---|---|---|
| 11402 | GET_UPLOAD_TIMESTAMP_FAIL | Failed to get upload timestamp | Retry operation |
| 32500 | SYSTEM_ERROR | Internal exception | Check logs, report issue |