错误码、线程与资源管理
12.1 服务错误码
| 数字码 | 名称 | 处理建议 |
|---|---|---|
| 1000 | SUCCESS | 服务调用成功；仍检查是否有结果 |
| 2001 | NETWORK_ERROR | 检查网络；有界重试 |
| 2002 | AUTH_ERROR | 核对 Key、包名、签名、数据集、能力 |
| 2003 | INVALID_ARGUMENT | 修正参数，勿无限重试 |
| 2004 | NO_ROUTE | 换起终点或提示暂无路线 |
| 2005 | SERVER_ERROR | 记录 requestId 联系服务方 |
| 2006 | CANCELLED | 已取消；通常不提示故障 |
getLastError() 提供 SdkException，可读取 getCode()、getRequestId()、getHttpStatus()、getRetryAfterMillis()。httpStatus=0 表示无 HTTP 响应，retryAfterMillis=-1 表示未取得有效 Retry-After。参数校验也可能同步抛 IllegalArgumentException，不能只依赖异步回调。
SdkLogger.setErrorLogger((source, code, requestId) ->
android.util.Log.w("MapSDK", source + " / " + code + " / " + requestId));
// 宿主日志代理不再需要时：SdkLogger.setErrorLogger(null);
12.2 定位错误码
| 原始码 | 统一代码 | 含义 |
|---|---|---|
| 0 | 成功 | 可使用位置 |
| 1 | PERMISSION_DENIED | 缺定位权限 |
| 2 | PROVIDER_DISABLED | 系统定位关闭 |
| 3 | TIMEOUT | 定位超时 |
| 4 | SOURCE_FAILURE | 位置源失败 |
| 5 | STOPPED | 定位已停止 |
| 6 | PRIVACY_DENIED | 未同意或已撤销授权 |
| 7 | ACCURACY_INSUFFICIENT | 无位置达到设定精度 |
定位错误通过 SukhaLocation.getError() 取得结构化信息，与搜索的 1000/200x 码分开处理。
12.3 线程与生命周期
地图、覆盖物、定位及导航控制器在主线程操作；异步服务回调也不要执行阻塞工作。同步网络方法只能在工作线程调用。共享 client 的销毁顺序：先停止定位/导航 → 销毁工具及服务 → MapView.onDestroy → 最后由拥有者 client.close。使用 MapsInitializer 的进程级默认会话时，只有全部使用者退出后才调用 MapsInitializer.destroy。
搜索对象可 cancel() 取消请求并继续复用；destroy() 后不可再调用。map.clear() 只清理地图相关对象，不能代替停止独立定位和搜索。Activity 重建后要重新绑定监听器。