处理错误

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

2D 图块和街景图像

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

列出时出错

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

required
您的请求缺少网址参数。请注意，错误消息会指明缺少哪个参数。
notFound、invalid

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

  • 对于常规地图图块，最大缩放级别取决于特定地图图块以及您请求的地图选项。

  • 对于常规地图图块，x 坐标必须在 [0, (2^缩放级别)-1] 的范围内。

  • 对于常规地图图块，y 坐标必须在 [0, (2^(zoom-1))-1] 的范围内。

  • 对于街景图块，缩放级别必须介于 0 和 5 之间（含 0 和 5）。

  • 对于街景图块，x 和 y 坐标范围与常规地图图块的范围相同，直至缩放级别为 5。此时，最大值为 imageHeight 或 imagewidth 除以 tileHeight 或 tileWidth。

forbidden：请求缺少有效的 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 时，您应该按照如下方式重试请求：中断的请求或大规模失败不会泛滥 Goodle 服务器，因为许多客户端会快速连续重试请求。这意味着在重试请求时，请使用指数退避算法。指数退避算法迫使您将请求及时分散，以便为服务器留出恢复时间。

例如，如果请求失败，则会在一秒后重试。但是，如果该尝试也失败，请在两秒钟后重试请求。如果该请求也失败，请在 4 秒后重试。因此，您只需将每个连续请求之间的时间长度加倍，即可有效地将其分散开来。

3D 图块

Google 服务器上的错误可能并不明显，因为您可以通过负责处理服务器错误的渲染程序访问仿真图块。

图块渲染器错误

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

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

常见错误

以下列表详细说明了您可能会遇到的最常见错误。

400：参数无效
API 密钥、查询参数、功能块/图块集 ID 无效或会话令牌过期。
403：权限遭拒
缺少 API 密钥、缺少 SSL 连接，或者您的 API 密钥尚未添加到 3D 图块的许可名单中。请与 Google 支持团队联系并提供您的项目 ID，以便将其添加到 Map Tiles API 的 3D 图块功能的许可名单中。
429：请求过多
您的配额已用尽。如需增加配额，请与 Google 支持团队联系。