腾讯定位 SDK 错误码枚举。

包含系统通用错误码、系统定位错误码和 SDK 自定义错误码。

开发者可以根据错误码快速定位问题,无需查阅官方文档。

Since

1.0.0

Enumeration Members

PermissionDenied: 201

【系统错误码】权限校验失败。

错误码:201

错误信息:Permission verification failed. The application does not have the permission required to call the API.

错误描述:权限校验失败,应用无权限使用该 API,需要申请权限。

可能原因:该错误码表示权限校验失败,通常为没有权限,却调用了需要权限的 API。

处理步骤:请检查是否有调用 API 的权限。

Since

1.0.0

ParameterError: 401

【系统错误码】参数检查失败。

错误码:401

错误信息:Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

错误描述:

  1. 必填参数为空。

  2. 参数类型不正确。

  3. 参数校验失败。无论是同步还是异步接口,此类异常大部分都通过同步的方式抛出。

可能原因:

  1. 必选参数没有传入。

  2. 参数类型错误 (Type Error)。

  3. 参数数量错误 (Argument Count Error)。

  4. 空参数错误 (Null Argument Error)。

  5. 参数格式错误 (Format Error)。

  6. 参数值范围错误 (Value Range Error)。

处理步骤:请检查必选参数是否传入,或者传入的参数类型是否错误。对于参数校验失败,阅读参数规格约束,按照可能原因进行排查。

Since

1.0.0

CapabilityNotSupported: 801

【系统错误码】该设备不支持此 API。

错误码:801

错误信息:Capability not supported. Failed to call the API due to limited device capabilities.

错误描述:该设备不支持此 API,因此无法正常调用。

可能原因:可能出现该错误码的场景为:该设备已支持该 API 所属的 Syscap, 但是并不支持此 API。

处理步骤:应避免在该设备上使用此 API,或在代码中通过判断来规避异常场景下应用在不同设备上运行所产生的影响。

Since

1.0.0

LocationServiceUnavailable: 3301000

【系统错误码】位置服务不可用。

错误码:3301000

错误信息:The location service is unavailable.

错误描述:位置服务不可用,位置服务相关的接口无法调用。

可能原因:

  1. 位置服务启动异常,导致应用和位置服务子系统通信失败,导致位置服务不可用。

  2. GNSS 芯片初始化失败导致 GNSS 定位功能失效。

  3. 网络定位服务异常,导致网络定位功能失效。

处理步骤:请停止调用该接口。

Since

1.0.0

LocationSwitchOff: 3301100

【系统错误码】位置功能的开关未开启导致功能失败。

错误码:3301100

错误信息:The location switch is off.

错误描述:位置功能的开关未开启导致功能失败。

可能原因:位置功能的开关未开启,导致持续定位,单次定位等基本功能不可用。

处理步骤:请提示用户开启位置功能的开关。

Since

1.0.0

ObtainGeographicalLocationFailed: 3301200

【系统错误码】定位失败,未获取到定位结果。

错误码:3301200

错误信息:Failed to obtain the geographical location.

错误描述:定位失败,未获取到定位结果。

可能原因:

  1. GNSS 信号弱,导致定位超时。

  2. 网络定位异常,导致定位超时。

  3. 定位结果不满足定位请求参数中的精度要求 (maxAccuracy),导致定位超时。

  4. 系统无缓存位置,导致获取上一次位置失败。

  5. 系统时间设置错误,导致获取位置失败。

处理步骤:

  1. 请移动至开阔地带再发起定位。

  2. 请检查设备是否能联网,设备是否插入 SIM 卡,WiFi 开关是否开启等。

  3. 请检查定位请求中的 maxAccuracy 字段是否合理。

  4. 系统无缓存位置的情况下,请使用 getCurrentLocation 接口获取实时位置信息。

  5. 请在"日期和时间"页面勾选自动设置。


Since

1.0.0

ReverseGeocodingQueryFailed: 3301300

【系统错误码】逆地理编码查询失败。

错误码:3301300

错误信息:Reverse geocoding query failed.

错误描述:逆地理编码查询失败。

可能原因:

数据网络比较卡顿,导致端侧的请求发送失败或者云端的结果未返回到端侧。

由于 X86 模拟器不支持逆地理编码功能,导致使用 X86 模拟器调试时逆地理编码查询失败。

处理步骤:

网络原因请尝试重试逆地理编码查询功能。

X86 模拟器原因建议在真机进行验证。

Since

1.0.0

GeocodingQueryFailed: 3301400

【系统错误码】地理编码查询失败。

错误码:3301400

错误信息:Geocoding query failed.

错误描述:地理编码查询失败。

可能原因:

1、请求参数有误,或根据参数无法查到结果。

2、数据网络比较卡顿,导致端侧的请求发送失败或者云端的结果未返回到端侧。

处理步骤:请检查请求参数或检查网络状态后重试

Since

1.0.0

QueryAreaInfoFailed: 3301500

【系统错误码】区域信息(包含国家码)查询失败。

错误码:3301500

错误信息:Failed to query the area information.

错误描述:区域信息(包含国家码)查询失败。

可能原因:未查询到正确的区域信息。

处理步骤:请停止调用查询区域码的接口。

Since

1.0.0

GeofenceOperationFailed: 3301600

【系统错误码】地理围栏操作失败。

错误码:3301600

错误信息:Failed to operate the geofence.

错误描述:地理围栏操作失败,包含添加,删除,暂停和恢复等操作。

可能原因:

  1. GNSS 芯片不支持地理围栏功能。

  2. 底层业务逻辑异常导致操作地理围栏失败。

处理步骤:请停止调用地理围栏操作接口。

Since

1.0.0

GeofenceCountExceedsLimit: 3301601

【系统错误码】地理围栏个数超过最大值限制导致添加围栏失败。

错误码:3301601

错误信息:The number of geofences exceeds the maximum.

错误描述:地理围栏个数超过最大限制导致添加围栏失败。

可能原因:

  1. 系统中存在的地理围栏个数超过最大值限制。

处理步骤:请在删除多余围栏之后再添加新的围栏。

Since

1.0.0

GeofenceIncorrectId: 3301602

【系统错误码】地理围栏 ID 错误导致删除围栏失败。

错误码:3301602

错误信息:Failed to delete a geofence due to an incorrect ID.

错误描述:地理围栏 ID 错误导致删除围栏失败。

可能原因:

  1. APP 调用删除地理围栏接口时传入的围栏 ID 错误。

处理步骤:请在调用删除地理围栏接口时传入正确的围栏 ID。

Since

1.0.0

NoResponseToRequest: 3301700

【系统错误码】请求无响应。

错误码:3301700

错误信息:No response to the request.

错误描述:某些异步请求需要用户点击按钮确认,或者需要 GNSS 芯片和网络服务器响应,这些场景下未收到响应导致业务失败。

可能原因:

  1. 用户未点击按钮确认。

  2. GNSS 芯片未响应。

  3. 网络服务器未响应。

处理步骤:请停止调用相关接口。

Since

1.0.0

WifiBluetoothScanFailed: 3301800

【系统错误码】启动 WiFi 或蓝牙扫描失败。

错误码:3301800

错误信息:Failed to start WiFi or Bluetooth scanning.

错误描述:在订阅 WiFi 蓝牙扫描信息时,可能会先启动 WiFi 蓝牙扫描,如果启动扫描失败则会返回错误码给 APP。

可能原因:

  1. WiFi 或蓝牙服务内部错误导致启动扫描失败。

  2. 低电量场景下,受功耗管控,导致无法发起扫描。

  3. WiFi 或蓝牙开关未开启。

处理步骤:重新关闭开启 WiFi 或蓝牙开关。

Since

1.0.0

GeofenceCoordinateTypeNotSupported: 880100

【SDK 错误码】地理围栏坐标类型不支持。

错误码:880100

错误信息:Geofence coordinate type not supported.

可能原因:

当前地理围栏请求使用的坐标系不被 SDK 支持(SDK 仅支持 GCJ-02 坐标系的地理围栏)

处理步骤:

  1. 确认 TencentGeofenceRequest 的 coordinateType 是否设置为 GCJ-02

  2. 如使用 WGS84 坐标,需先转换为 GCJ-02


Since

1.0.0

GeofenceNotificationsLengthMismatch: 880200

【SDK 错误码】地理围栏 notifications 长度与 monitorEvents 不一致。

错误码:880200

错误信息:Geofence notifications length does not match monitorEvents length.

可能原因:

TencentGeofenceRequest 的 notifications 已设置,但其长度与 monitorEvents 长度不一致。notifications 与 monitorEvents 中的元素需要按下标一一对应。

处理步骤:

  1. 如果不需要在事件触发时弹出系统通知,可以不传 notifications 字段。

  2. 如果需要弹出通知,请确保 notifications.length === monitorEvents.length,且 notifications[i] 是 monitorEvents[i] 触发时要弹出的通知。


Since

1.2.0

PrivacyPolicyNotAgreed: 990100

【SDK 错误码】隐私政策未同意。

错误码:990100

错误信息:Privacy policy not agreed.

可能原因:

用户尚未同意隐私政策,SDK 无法正常工作

处理步骤:

  1. 在应用启动时展示隐私政策弹窗,用户同意后调用 TencentLocationSDK.setPrivacyPolicyAgreement(true)

  2. 获取用户同意后再调用 TencentLocationSDK.init(this.context, 'apiKey', 'deviceID') 初始化 SDK

  3. 确保在调用任何定位相关 API 前已完成隐私政策同意流程


Since

1.0.0

ContinuousLocationAlreadyStarted: 990200

【SDK 错误码】连续定位已在运行中。

错误码:990200

错误信息:Continuous location is already started.

可能原因:

在未调用 stopContinuousLocation() 的情况下再次调用了 startContinuousLocation()

处理步骤:

  1. 在再次调用 startContinuousLocation() 之前,请先调用 stopContinuousLocation() 停止当前定位

  2. 检查代码逻辑,确保不会重复启动连续定位


Since

1.1.0