# 错误与故障排查

先确定问题发生在哪一层：上传、建图、地图浏览、定位请求，还是 AR 对齐。不要在没有证据时同时修改扫描数据、内参和坐标转换，否则很难判断真正原因。

## 上传与建图

| 现象 | 首先检查 |
| --- | --- |
| ZIP 无法识别 | 文件是否真的为 ZIP，内部是否包含所选输入类型要求的文件。 |
| 设备类型不匹配 | 是否选择了正确的 LiDAR 品牌，E57 是否来自该设备并保留元数据。 |
| 图片与位姿不匹配 | 文件名、扩展名和大小写是否与位姿表完全一致。 |
| 密度过低 | 移动式采集间距是否超过约 2 m，固定站是否超过约 5 m；门口和转角是否缺站。 |
| Parsing 失败 | 视频能否完整播放，格式是否为当前界面接受的 MP4/MOV/M4V，网盘链接是否直接指向单个可下载文件。 |
| Building 失败 | 保留地图 ID、失败时间、Input 和 Pipeline 版本；先按卡片提示重试一次，重复失败再联系支持。 |

## 定位 HTTP 状态

| 状态 | 含义与处理 |
| --- | --- |
| `400` | 请求字段、图片或四个内参缺失/无效。 |
| `401` | API Key 缺失、失效或格式错误。 |
| `403` | 已识别用户，但无权访问 Map/Project，或 Key 组合不匹配。 |
| `422` | 本次图片没有得到可靠位姿；换用更清晰、包含更多已建图固定细节的图片。 |
| `429` | 请求过快；按响应提示退避，不要立即并发重试。 |
| `5xx` | 服务暂时异常；保留当前 AR 对齐，稍后重试。 |

## 结果看起来不对

- **内容镜像或旋转 180°**：相机 CV→graphics 轴转换缺失或做了两次。
- **响应回来时内容跳动**：使用了“当前相机”而不是拍摄上传图片那一帧的 AR 变换。
- **始终固定偏移**：Content、地图 Origin 和定位位姿不在同一地图坐标系。
- **只在某些设备失败**：检查该设备上传图片的实际分辨率、旋转、裁剪与内参。
- **一段区域持续失败**：在 Space Studio 检查该区域建图相机与 Points 覆盖，必要时补扫并重建。

联系支持时请提供 Portal 环境、地图 ID、发生时间和时区、输入类型、Pipeline 版本、HTTP 状态及已去除 Key 的最小请求信息。不要发送 API Key、Map Key、Project Key 或包含客户数据的完整原始包，除非通过已确认的安全渠道。