Appearance
错误码
访问被拒绝时，平台返回 JSON 错误体，程序应按其中的 code 判断原因。
错误体格式
json
{ "code": "TOKEN_REQUIRED", "message": "该服务需要 API Key" }Content-Type: application/json;charset=UTF-8，Cache-Control: no-store。- 未登录访问其他需要登录的地址时，错误体可能多出
success、timestamp等字段，如{"success":false,"code":"UNAUTHORIZED","message":"用户未登录","timestamp":…}。请只读code，不要依赖success字段。 - 错误响应同样带跨域响应头，浏览器中的跨域页面能读到错误体。
访问控制的错误码
| 状态 | code | message | 含义与处理 |
|---|---|---|---|
| 401 | TOKEN_REQUIRED | 该服务需要 API Key | 服务是「API Key」级别，请求没有带 Key。带上 Key 后重试 |
| 401 | TOKEN_INVALID | API Key 无效或已过期 | Key 不存在、写错、已撤销或已过期；Key 属于其他工作空间；或请求来源不在 Key 的域名、IP 白名单内。检查 Key 与白名单 |
| 401 | UNAUTHORIZED | 用户未登录 | 服务是「私有」级别，需要登录；或访问的服务不存在（见下文）。第三方程序请让服务改为「API Key」级别并带 Key |
| 403 | FORBIDDEN | 没有该服务的访问权限 | 已登录，但对服务所在工作空间没有读权限（写操作则是没有写权限）。请工作空间管理者授权 |
| 405 | METHOD_NOT_ALLOWED | 编辑接口只接受 POST | 用 GET 或 HEAD 调用了要素编辑接口，改用 POST |
| 400 | BAD_PATH | 非法的请求路径 | 地址中含 .、.. 路径段、//、;、反斜杠，或编码的点、斜杠、百分号等。服务名、目录名、要素 ID 中含 % 时同样会被拒绝 |
带了 Key 时，平台只按 Key 判断，不再看登录状态：Key 无效即返回 TOKEN_INVALID。公开服务不看 Key，带了无效 Key 也照常返回。
不存在的服务
为了不透露某个服务是否存在，访问不存在的服务时：
| 请求方 | 结果 |
|---|---|
| 匿名，未带 Key | 401 UNAUTHORIZED |
| 带了 Key | 401 TOKEN_INVALID |
| 已登录 | 404 |
所以匿名访问时收到 UNAUTHORIZED，也可能是服务名或路径写错了，请先核对服务地址。
其他常见错误
| 状态 | 情形 |
|---|---|
404 NOT_FOUND「方案还没有发布版本」 | 地图方案还没有保存过版本，先在编辑器中「保存版本」 |
404 NOT_FOUND「方案不存在」 | 地图方案 id 写错或已删除 |
| 404「服务未启用 WMS」「服务未启用 WFS」「服务未启用 WMTS」等 | 服务发布时没有勾选该能力 |
| 503 | 服务已停止（消息含「已停止」），或服务繁忙、数据源暂不可用。已停止的服务请在控制台启动 |
OGC 服务（WMS、WFS、WMTS、TMS、WCS、OGC API）的参数错误按各自的规范返回异常报告（如 MissingParameterValue、InvalidParameterValue、LayerNotDefined）。访问控制的错误在这些地址上同样按协议的异常格式返回（OGC API 为 application/problem+json），状态码与 code 同上表，见 OGC 服务概览。
JS SDK 的错误码
SDK 的所有失败都抛出 GeoBridgeError，包含 status（HTTP 状态码，没有响应时为 0）、code、message 与 url。url 与 message 中的 Key 已替换为 ***，可以放心打印。
code | 含义 |
|---|---|
TOKEN_REQUIRED、TOKEN_INVALID、UNAUTHORIZED、FORBIDDEN 等 | 平台返回的错误码，原样作为 code，含义见上表 |
SERVICE_ERROR | 服务以 ArcGIS 风格返回的错误（{"error":…}，可能是 HTTP 200），如服务不存在或已停止 |
HTTP_<状态> | 其他非 2xx 响应，且响应体中没有平台错误码，如 HTTP_404、HTTP_500 |
NETWORK | 网络错误或读取响应失败；跨域被浏览器拒绝时也是这个错误（浏览器不区分原因） |
TIMEOUT | 超过 timeoutMs（默认 30 秒），每次重试单独计时 |
ABORTED | 调用方传入的 signal 已中止 |
BAD_RESPONSE | 响应不是有效的 JSON，或缺少必要的字段 |
FOREIGN_URL | 地址不属于配置的平台，SDK 拒绝发送（避免泄露 Key） |
REDIRECT | 平台地址发生了重定向。SDK 不跟随重定向，请把 baseUrl 直接写成最终地址（常见于 http 被重定向到 https） |
ID_CONFLICT | 往地图上加服务时，已有同 id 的数据源或图层 |
INVALID_STYLE | 服务返回的样式中有图层缺少 id |
- 网络错误与 429、502、503、504 响应会自动重试（只重试 GET，默认 2 次，指数退避）；其他 4xx 不重试。
- 区分错误原因的完整示例见访问控制示例。