百度地图API返回240错误：APP服务被禁用如何解决？

Question

百度地图API返回240错误“APP服务被禁用”通常是由于当前使用的AK（Access Key）未正确绑定或启用地图相关服务所致。常见问题：在百度地图开放平台创建应用后，仅生成AK但未在“控制台-应用管理”中开启“JavaScript API”或“Web服务API”等对应服务，导致请求被拒绝。此外，AK绑定的域名或IP与实际调用环境不符，也会触发该错误。如何解决？需登录百度地图开放平台，进入应用详情页，检查并启用所需API服务，并确保调用来源与AK绑定的合法域名或IP一致。

Answer 1

一、问题背景与初步诊断

当开发者在调用百度地图API时，遇到错误码“240：APP服务被禁用”，通常表明当前使用的Access Key（AK）存在配置或权限问题。该错误并非网络或代码层面的异常，而是平台级的服务授权控制机制触发的结果。

从最基础的视角来看，此类问题多源于以下两类原因：

• 未在百度地图开放平台中启用对应的API服务（如JavaScript API、Web服务API等）；
• AK绑定的调用来源（域名/IP）与实际请求环境不一致。

对于刚接入百度地图API的团队而言，容易忽略“服务启用”这一关键步骤——即便已成功生成AK，若未手动开启所需服务，则所有相关接口请求均会被拦截并返回240错误。

二、深入分析：服务启用与AK绑定机制

百度地图开放平台采用“按需启用”的安全策略，即每个AK必须显式开启其所依赖的API服务。这种设计旨在防止滥用和未授权访问。

以常见的前端地图渲染为例，若使用了<script src="https://api.map.baidu.com/api?v=3.0&ak=YOUR_AK">方式加载地图，但未在控制台启用“JavaScript API”，则即使AK正确也会返回240错误。

此外，平台对调用来源进行严格校验，支持以下几种绑定模式：

绑定类型	适用场景	注意事项
浏览器端IP	本地开发调试	需确保公网IP固定，动态IP易失效
域名白名单	线上Web应用	子域名需单独添加或使用泛解析
服务器IP	后端调用Web服务API	不适用于前端JS调用
无限制（慎用）	测试阶段	存在安全风险，建议仅临时开启

三、排查流程与解决方案

为系统化解决240错误，建议按照如下流程执行排查：

1. 登录百度地图开放平台，进入“控制台-应用管理”；
2. 选择对应的应用，查看其AK详情页；
3. 检查“服务列表”中是否已启用所需的API（如JavaScript API、Geocoding API等）；
4. 确认“启用状态”为“已启用”，否则点击“立即启用”；
5. 核对“绑定信息”中的域名或IP是否覆盖当前调用环境；
6. 若为本地开发，可临时添加开发机公网IP；
7. 若为线上部署，确保主域及常用子域（如map.example.com）均已加入白名单；
8. 修改后保存，并等待5分钟使配置生效；
9. 重新发起API请求，观察是否仍返回240错误；
10. 可通过浏览器开发者工具的Network面板验证请求响应头与body内容。

四、高级调试与自动化检测方案

对于具备一定运维能力的团队，可构建自动化检测脚本定期验证AK可用性。以下是一个基于Node.js的健康检查示例：

const https = require('https');

function checkBaiduMapAPI(ak) {
    const url = `https://api.map.baidu.com/geocoding/v3/?address=北京市中关村&output=json&ak=${ak}`;

    https.get(url, (res) => {
        let data = '';
        res.on('data', chunk => data += chunk);
        res.on('end', () => {
            const json = JSON.parse(data);
            if (json.status === 240) {
                console.error('[ERROR] APP服务被禁用，请检查AK服务启用状态与域名绑定');
            } else if (json.status === 0) {
                console.log('[OK] API调用正常');
            } else {
                console.warn('[WARNING] 其他错误:', json.message);
            }
        });
    }).on('error', e => {
        console.error(`请求失败: ${e.message}`);
    });
}

// 使用示例
checkBaiduMapAPI('your-access-key-here');
    

五、可视化排查流程图

为了帮助团队快速定位问题根源，以下是完整的故障排查逻辑图：

graph TD
            A[收到240错误] --> B{是否已启用所需API?}
            B -- 否 --> C[登录开放平台]
            C --> D[进入应用详情页]
            D --> E[启用JavaScript API/Web服务API]
            E --> F[保存配置]
            B -- 是 --> G{调用来源是否匹配?}
            G -- 否 --> H[检查域名/IP绑定]
            H --> I[添加当前环境地址到白名单]
            I --> J[等待配置生效]
            G -- 是 --> K[检查AK是否泄露或过期]
            K --> L[考虑重置AK并更新部署]
            J --> M[重新发起请求]
            F --> M
            M --> N{是否仍报错?}
            N -- 是 --> O[联系百度地图技术支持]
            N -- 否 --> P[问题解决]