周玉坤举重1. 遇到UNKNOWN_ERROR时的心态调整
第一次看到高德地图API返回{"status":"0","info":"UNKNOWN_ERROR","infocode":"20003"}时，我正赶着交付项目。这个错误就像个黑盒子，除了告诉你"出错了"，什么线索都不给。经过多次实战，我发现这类问题往往出在基础配置和请求细节上。
记得有个紧急项目，客户要求次日上线地点搜索功能。我按照文档写完代码，测试时却一直收到20003错误。当时急得满头大汗，后来才发现是密钥类型选错了——把Web端密钥用在了服务端调用。这种低级错误最容易让人崩溃，但也是最好解决的。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 错误码20003的常见原因分析
2.1 密钥问题排查
密钥问题是导致20003错误的头号杀手，具体可能包括：
-
密钥类型不匹配：高德地图区分Web端(JS API)、Android/iOS端、服务端(Web服务API)三种密钥。用Web端密钥调用服务端API就会报20003。我有次在Spring Boot项目里复用了前端密钥，调试两小时才反应过来。
-
密钥未启用对应服务：在控制台新建密钥时，需要勾选"Web服务API"选项。曾经帮同事排查问题时发现，他的密钥只勾选了"JavaScript API"。
-
密钥余额耗尽：虽然文档没说20003会因欠费触发，但我实测发现当QPS超限或余额为0时，有时会返回此错误码。建议在控制台查看"使用统计"。
2.2 请求参数问题
即使密钥正确，参数错误也会导致20003：
-
必填参数缺失：比如
inputtips接口必须同时传keywords和key参数。有次我漏写keywords参数，返回的就是20003而非参数缺失提示。 -
参数格式错误：特殊字符未做URL编码是常见问题。比如搜索"北京&上海"，需要先编码成"北京%26上海"。这是我用Postman对比测试发现的细节。
2.3 网络环境问题
某些特殊场景也会触发20003：
-
服务器IP未加入白名单：如果控制台设置了IP白名单，记得添加服务器公网IP。我们测试环境用Nginx转发请求时就栽过跟头。
-
HTTPS证书问题：旧版JDK可能因证书链不完整