新闻

所有端点统一采用更清晰的错误格式

错误响应不是 API 的脚注,它和成功响应一样,是每个集成都依赖的契约的一部分。我们已在 My Geocode 的所有原生端点上统一了错误格式,因此无论失败来自 API 的哪个部分,看起来都一样。

无论请求失败是因为缺少参数、密钥无效、配额用尽还是坐标格式错误,响应都遵循单一、可预测的结构。这种一致性意味着,针对一个端点写一次的错误处理代码,在其他每个原生端点上都以同样方式工作,无需为每个端点单独编写处理逻辑。

与配额相关的失败值得特别一提,因为这是活跃集成最常遇到的一类错误。当请求会超出某个密钥或某个网络的配额时,响应会明确说明这一点,而每个响应中本已存在的配额响应头,X-Quota-LimitX-Quota-UsedX-Quota-Free-Remaining 等,会准确告诉您在失败的请求之前还剩多少余量。这样的组合意味着,客户端仅凭响应本身就能区分配额问题、身份验证问题和错误请求,无需猜测。

兼容主机是这一标准化的有意例外,而且理由充分。它们的全部目的就是完全复现另一家服务商的请求和响应结构,其中也包括错误的样子。一个按 Bing Maps REST Services 格式构造的请求如果失败,仍会得到 Bing 自己格式的错误,因为无论成功还是失败都精确匹配原有结构,正是兼容替换主机的意义所在。在那里统一错误格式,反而会破坏主机存在的意义,也就是兼容性本身。

对于基于我们原生端点构建的任何应用,这种更清晰的格式应该会让错误处理的编写和维护明显更简单。一套解析例程、一组预期字段,以及在 /v1/forward/v1/reverse/v1/ip/v1/timezone/v1/elevation/v1/autocomplete/v1/postcode 上完全一致的行为。

错误格式的完整文档,包括字段名称和常见原因,见 /docs/errors/。如果您的集成目前为不同的原生端点编写了不同的错误处理分支,现在正是将其简化为一个的好时机。