处理错误

欧洲经济区 (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 卫星图块。如需了解更多信息，请参阅针对 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 服务器。这意味着在重试请求时使用指数退避算法。指数退避算法会强制您在一段时间内分散请求，以便服务器有时间恢复。

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

3D 图块

您可能不会注意到 Google 服务器的错误，因为您是通过渲染器访问照片级真实感的图块，而渲染器负责处理服务器错误。

图块渲染器错误

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

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

常见错误

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

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

403：权限遭拒