此页面由 Cloud Translation API 翻译。

处理错误

欧洲经济区 (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 之间（含边界值）。
对于街景图块，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 卫星图块。如需了解详情，请参阅针对欧洲经济区客户的 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 服务器不堪重负，因为许多客户端会尝试快速连续地重试请求。这意味着在重试请求时，您需要使用指数退避算法。指数退避算法会强制您在一段时间内分散请求，以便服务器有时间恢复。

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

3D 图块

Google 服务器的错误可能并不明显，因为您是通过渲染器访问照片级逼真图块的，而渲染器负责处理服务器错误。

图块渲染器错误

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

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

常见错误

下表详细列出了您可能会遇到的一些最常见错误。

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

403：权限遭拒