为何调用Google Maps Places库getDetails查询地点持续返回QUERY_OVER_LIMIT错误

错误根因 #

你触发的不是公开的全局配额限制（即后台标注的每分钟6000次、官方文档标注的每秒100次），而是Google未公开公示的单客户端短时间突发限流规则：大量开发者实测显示，getDetails() 接口对单用户端的短时间请求阈值远低于全局配额，普遍为10秒内不超过10次请求，刚好对应前10次请求正常、后续持续报错的现象。
固定300ms间隔的请求方式依然触发错误，是因为前端网络请求存在不可控的延迟堆积，会导致短时间内实际请求密度超过隐性阈值。

可行解决方案 #

1. 新增指数退避重试逻辑（优先选择） #

碰到 QUERY_OVER_LIMIT 状态时自动延迟重试，无需全局降低所有请求的发送频率，仅对触发限流的请求做延迟处理，整体用户体验损失最小。参考实现代码如下：

// 带指数退避的getDetails封装，仅拉取需要的website字段减少配额消耗
async function getPlaceDetailsWithRetry(placeId, retryCount = 0) {
  const MAX_RETRY_TIMES = 3;
  const placesService = new google.maps.places.PlacesService(mapElement);
  const request = {
    placeId: placeId,
    fields: ['website'] // 只请求需要的字段，不要请求全量字段浪费配额
  };

  return new Promise((resolve, reject) => {
    placesService.getDetails(request, (result, status) => {
      if (status === google.maps.places.PlacesServiceStatus.OK) {
        return resolve(result);
      }
      // 触发限流且未达重试上限时，指数退避后重试
      if (status === google.maps.places.PlacesServiceStatus.QUERY_OVER_LIMIT && retryCount < MAX_RETRY_TIMES) {
        const waitTime = 1000 * Math.pow(2, retryCount); // 首次等1s，第二次2s，第三次4s
        setTimeout(() => {
          resolve(getPlaceDetailsWithRetry(placeId, retryCount + 1));
        }, waitTime);
        return;
      }
      return reject(status);
    });
  });
}

2. 限制并发请求数 #

将 getDetails() 的并行请求数控制在2以内，同时保持150~200ms的请求间隔，既不会显著增加整体请求耗时，也能避开突发限流阈值。

3. 分层渲染内容 #

优先将 nearbySearch() 就能拿到的餐厅基础信息（名称、评分、地址等）渲染给用户，后台异步拉取官网等详情信息，拉取成功后再补填到页面上，用户完全感知不到请求延迟。

内容的提问来源于stack exchange，提问作者CH Nguyen