API使用指南 - 中文

本指南介绍如何使用我们的 API 服务，包括身份认证、错误处理、延迟诊断、限流策略以及支持资源。

🔐 身份认证

在调用我们的 API 时，您必须在每个请求中以 URL 参数的形式携带访问令牌（token）：

http://<ip:port>/your-endpoint?token=your_access_token

如需获取访问令牌，请先注册。

所有 API 响应都会返回 HTTP 状态码 200 OK，无论业务结果是否成功。

业务层结果需要通过返回体中的 code 字段来判断。

{
  "code": 0,
  "message": "",
  "data": { ... }
}

⚠️ 若 HTTP 状态码不是 200，表示系统级错误（如超时、平台异常等），请联系我们进一步排查。

· 201 表示请求的资源不存在（如商品或文章未找到），请求本身成功执行，因此仍计费。

虽然大多数请求会在数秒内完成，我们建议将请求超时时间设置为 至少 60 秒。

这并不代表 API 很慢，而是为了避免由于短暂的网络抖动或客户端超时导致重复请求或误判错误。

如果您发现响应时间异常变长，可以通过 /ping 接口测试与服务器的网络连接：

正常响应通常在几百毫秒内返回；

若 /ping 请求明显延迟，可能是网络限制或地区性访问问题；

我们目前提供两个环境，针对不同地区进行优化：

地区	推荐环境
中国大陆	`prod-cn`
中国大陆以外地区	`prod-global`

切换到合适的环境可显著提升速度与稳定性；

若仍不确定使用哪一个环境或遇到问题，请联系我们，我们将协助您解决。

API 没有通用的调用速率限制。

但部分高并发接口可能会设定特定的速率（如每分钟或每小时），具体说明请参考各接口文档。

如有问题、对接需求或希望获取定制解决方案，请通过支持页面联系我们：