处理错误

欧洲经济区 (EEA) 开发者

发出请求后，您可能会收到包含错误详细信息的响应。

2D 图块和街景图像

以下列表详细介绍了您在使用 2D 瓦片和街景图像时可能会遇到的错误。

错误列表

以下列表详细介绍了您在使用 Map Tiles API 时可能会遇到的错误。

required

您的请求缺少网址参数。请注意，出错提示会指明缺少哪个参数。

notFound、invalid

您的 x、y 或 z 值超出范围。

对于常规地图图块，最大缩放级别取决于特定地图图块以及您请求的地图选项。
对于常规地图图块，x 坐标必须在 [0, (2^zoom)-1] 范围内。
对于常规地图图块，y 坐标必须在 [0, (2^(zoom-1))-1] 范围内。
对于街景图块，缩放级别必须介于 0 到 5 之间（含 0 和 5）。
对于街景图块，x 和 y 坐标范围与常规地图图块相同，直到缩放级别 5。此时，最大值为 imageHeight 或 imagewidth 除以 tileHeight 或 tileWidth。

forbidden：

可能的原因：

请求中缺少有效的 API 密钥。
消息：Your request cannot be served. Please ensure the parameters and request type are valid for your account and region.

如果项目关联的结算账号地址位于欧洲经济区 (EEA)，则无法使用 2D 卫星图块。如需了解详情，请参阅针对 EEA 客户的 Map Tiles API 调整。

expired

您的 session 令牌已过期。会话令牌自创建之日起两周内有效。请注意，此信息可能会发生变化，恕不另行通知。如果您收到此错误，则必须获取新的会话令牌，如使用会话令牌中所述。

badRequest

您的请求格式不正确。出现此错误的常见原因包括：

您指定了 terrain 地图类型，但未包含 roadmap 图层。
您为非路线图地图类型添加了 styles 数组。
您在街景元数据请求中同时发送了纬度/经度值和全景图片 ID。

quotaExceeded、rateLimitExceeded

您的应用已超出其允许的配额，或超出了其允许的每秒查询次数。

错误示例

{
  "error": {
    "code": 403,
    "message": "The request is missing a valid API key.",
    "errors": [
      {
        "message": "The request is missing a valid API key.",
        "domain": "global",
        "reason": "forbidden"
      }
    ],
    "status": "PERMISSION_DENIED"
  }
}

重试请求

当请求失败并显示 quotaExceeded 和 rateLimitExceeded 时，您应重试请求，以免损坏的请求或大规模故障导致 Google 服务器过载，因为许多客户端会尝试快速连续重试请求。这意味着您在重试请求时应使用指数退避算法。指数退避算法会强制您在一段时间内分散请求，以便服务器有时间进行恢复。

例如，如果请求失败，请在 1 秒后重试。但如果该尝试也失败，请在两秒后再次重试请求。如果该请求也失败，则在 4 秒后重试。因此，您只需将每个后续请求之间的时间长度加倍，即可有效分散每个后续请求。

3D 图块

Google 服务器中的错误可能对您来说并不明显，因为您是通过渲染程序访问 Photorealistic 3D Tiles，而渲染程序负责处理服务器错误。

图块渲染器错误

例如，当发生服务器错误时，CesiumJS 渲染器通常会静默失败，这可能会导致各种问题，从崩溃、空白屏幕到特定图块无法加载。

您用于调试服务器错误的方法取决于您使用的特定渲染程序。对于基于浏览器的渲染程序（例如 CesiumJS），您可以使用大多数浏览器内置的工具来检查网络流量。例如，您可以使用 Chrome 开发者工具。

常见错误

以下列表包含您可能会遇到的最常见错误的详细信息。

400：参数无效: API 密钥、查询参数、图块/图块集 ID 无效，或会话令牌已过期。
400：该值无效: 确保发出 createSessionToken 请求时使用的 mapType 与后续图块端点中使用的 mapType 匹配。例如，streetview 会话令牌不能用于请求 roadmap 图块。

403：权限遭拒