Mapbox boundaries 请求出现 402 - Payment required

2026-10-24支付老李

结论

402 - Payment required 不一定意味着 Mapbox 账户欠费。对于 mapbox.boundaries-pos4-v3，它更可能表示当前账户或 access token 没有 Mapbox Boundaries 数据集的有效访问权限。

如果此前可以使用，近期才开始报错，原因可能是试用或临时授权到期、账户订阅状态变化、应用更换了 token，或 Mapbox 调整了该 tileset 的访问控制。管理后台没有未结账单，也不能证明当前账户拥有 Boundaries 产品授权。

为什么正常运行两周后才出现 402

Mapbox Boundaries 并不是普通的公开 vector tileset。基础 Mapbox GL 地图可以正常加载，不代表账户自动拥有 Boundaries 数据的访问权限。

可能的原因有：

账户的试用期已经结束。
Mapbox 曾临时向该账户开放数据集，随后撤销或调整了授权。
开发环境与当前环境使用了不同的 access token。
token 属于另一个没有 Boundaries 权限的 Mapbox 账户。
token 被重新生成、轮换或替换，新 token 没有预期的配置。
Boundaries 订阅、合同或组织成员关系发生了变化。
tileset 版本或访问策略有所调整。

要确定原因，还需检查账户的授权记录。仅凭 402 无法判断究竟是欠费、试用到期，还是缺少产品权限。

排查步骤

1. 确认实际使用的 access token

即使 map.addSource() 中没有显式填写 token，Mapbox GL JS 仍会使用初始化时配置的 token。先在浏览器中确认请求实际使用的是哪个 token，不要只检查源代码里的预期配置。

mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';

const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/streets-v12'
});

map.on('load', () => {
    map.addSource('pos-4', {
        type: 'vector',
        url: 'mapbox://mapbox.boundaries-pos4-v3'
    });
});

在浏览器开发者工具的 Network 面板中找到失败的请求，核对以下内容：

请求中的 access_token
HTTP 状态码
响应正文
请求的 tileset ID
Referer、域名和运行环境

不要在日志、工单截图或公开仓库中暴露完整 token。

2. 判断是否只有 Boundaries 请求失败

如果底图和其他公开 tileset 都能正常加载，只有下面的 source 返回 402：

{
    type: 'vector',
    url: 'mapbox://mapbox.boundaries-pos4-v3'
}

问题更可能出在 Boundaries 产品授权上，而不是整个 Mapbox 账户的付款状态。

可以用同一个 token 加载一项账户明确有权访问的资源进行对比。测试时请选择自己账户中的 tileset，或当前 Mapbox 文档明确允许访问的资源，不要默认所有 mapbox.* tileset 都是公开的。

3. 核对 token 所属账户

Mapbox access token 与账户绑定。本地开发可能使用个人账户的 token，而生产环境通过环境变量注入了组织账户或其他成员的 token。

检查 token 的来源，例如：

mapboxgl.accessToken = process.env.MAPBOX_ACCESS_TOKEN;

如果使用构建工具，浏览器端环境变量的名称可能不同。例如，Vite 通常只会向客户端暴露符合其前缀规则的变量：

mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN;

重点检查最终构建产物中注入的是否为预期 token，以及该 token 所属账户是否拥有 Boundaries 授权。

4. 检查产品权限，不要只看账单页面

管理后台显示”没有 billing issues”，只能说明目前没有明显的未结付款问题。还要确认以下事项：

账户是否订阅了 Mapbox Boundaries。
试用是否已经结束。
当前组织是否仍拥有相关许可。
token 所属账户是否为获得许可的账户。
授权是否限制使用环境、域名或项目。
当前使用的 tileset 版本是否包含在授权范围内。

Mapbox 的产品名称、控制台入口和授权方式可能发生调整，应以当前账户合同和官方控制台显示的信息为准。

5. 联系 Mapbox 支持确认 entitlement

如果已经确认 token 和账户无误，可以向 Mapbox 支持提供以下信息：

Mapbox 账户或组织名称
失败的 tileset ID：mapbox.boundaries-pos4-v3
HTTP 状态码：402
错误首次出现的准确时间和时区
脱敏后的 token 标识，例如只保留开头和结尾的少量字符
失败请求的响应正文及 request ID（如果响应头中存在）
该账户是否申请过试用或签订过 Boundaries 许可

Mapbox 需要从服务端确认账户的 entitlement 状态。修改前端代码无法补上缺失的服务端产品授权。

代码层面的错误处理

可以监听 source 加载错误，并向用户显示清晰的提示。这只能改善出错时的体验，无法解决授权问题。

map.on('error', (event) => {
    const error = event.error;

    if (error && error.status === 402) {
        console.error(
            'Mapbox resource access was rejected. Check the account, token, and Boundaries entitlement.'
        );
        return;
    }

    console.error('Mapbox error:', error);
});

如果 Boundaries 图层不是页面的核心功能，可以在加载失败后禁用相关功能，避免整个地图界面无法使用：

map.on('error', (event) => {
    if (event.error?.status === 402) {
        const controls = document.querySelector('#boundary-controls');

        if (controls) {
            controls.setAttribute('aria-disabled', 'true');
        }
    }
});

注意事项

不要试图通过反复创建 token、修改 source ID 或在前端重试来绕过 402。如果缺少产品授权，这些操作无法恢复访问。

也不要认为公开 token 可以访问公开命名空间下的所有资源。token 是否有效、资源是否公开，以及账户是否获得某个付费数据产品的许可，是三个不同的问题。

排查这个错误时，应先检查 Boundaries 访问资格是否失效或发生变化，而不是只按信用卡扣款失败处理。如果代码和 token 都没有变化，服务却突然失效，应请 Mapbox 支持核查试用期限、订阅状态和服务端授权记录。