# API使用指南

本指南介绍如何使用我们的 API 服务，鉴权、响应、速率限制和支持返馈资源。

## Authorization/鉴权
要访问我们的 API，您必须在每个请求的请求头中添加您的API秘钥进行身份验证：

- 请求头
```js
Authorization: Bearer <your_apikey>
```
- 示例请求

```js
curl -X POST https://api.getoneapi.com/api/douyin/user_detail 
     -H "Content-Type: application/json" 
     -H "Authorization: Bearer 5hlBzQDigT4GZJRTL3GeUSxIAC2W0t4gjvn8fizJCCsawhFS1I2R4T8DbhqXYV6v" 
     -d '{"sec_user_id": "xxxxx"}'
```
要获取API密钥，请[注册](https://getoneapi.com/register)。现在注册，将赠送您一定的请求配额，供您免费试用！

## Response/响应
- 所有 API 响应都返回 HTTP 状态代码 200 OK，无论业务结果如何。
- 您必须依赖 JSON 响应主体中的 code 字段来确定业务级结果。

示例响应
```js
{
  "code": 200,
  "message": "",
  "data": { ... }
}
```
业务代码参考
| code | 说明 | 是否计费 | 建议处理方式 |
| --- | --- | --- | --- |
| 200 | 请求成功，`data` 中为接口返回数据 | 是 | 正常处理数据 |
| 0 | 请求失败，例如参数不正确、或其他业务异常 | 否 | 可检查参数；如为临时性失败可有限重试 |
| 301 | 账户余额不足 | 否 | 请充值后重试 |
| 302 | 当前 API 密钥的可用额度不足 | 否 | 请在控制台调整该 API 密钥额度，或更换其他可用密钥 |
| 401 | 未授权：未提供 API 密钥、密钥无效、密钥已禁用或已删除 | 否 | 检查 `Authorization: Bearer <API_KEY>` 请求头及密钥状态 |
| 403 | 账户不可用：账户已被禁用 | 否 | 请联系支持人员 |
| 404 | API 不存在、已下线或暂不可用 | 否 | 检查请求路径，或前往定价/文档页面确认接口状态 |
| 429 | 请求速率超过当前限制 | 否 | 请等待后重试，并降低并发或请求频率 |


超时建议
:::highlight blue 💡
虽然大多数 API 请求会在几秒钟内响应，但我们建议将请求超时设置为至少 60 秒。
这并不表示我们的 API 很慢——它只是有助于避免由于临时网络问题或客户端超时而导致的意外错误或重复收费。
:::

重试/切换策略
:::highlight blue 💡
- 虽然大多数 API 请求会在几秒钟内响应成功并返回数据，但也有部分不太稳定的接口，可以尝试多次请求（建议5次或5次以内，否则会触发风控，导致账户异常！），直到请求成功，请勿担心重复计费，只有成功的请求code=200才会计费。
- 部分接口存在多版本，V1、V2... 可以加入重试切换策略，在请求失败时切换另一个版本再次重试请求（注意：不同版本之间可能存在响应数据结构不一致的情况，请自行比对）。
:::


## Request rate/速率限制

平台采用按账户的 RPS（Requests Per Second，每秒请求数）限速机制，以保障接口稳定性和账户安全。

- 新注册账户默认拥有 **10 RPS**。
- 账户 RPS 作用于整个账户，**同一账户下的全部 API 密钥共享该请求速率**；创建多个 API 密钥不会增加总 RPS。
- 您可以在控制台的 **RPS** 页面开通或升级套餐，最高可升级至 **100 RPS**。
- 部分 API 可能配置独立的固定 RPS 限制。此类接口的独立限制优先级高于账户 RPS，账户升级不会覆盖该接口的固定限制；请以对应 API 文档或定价页标注为准。
- 限速采用平滑的令牌桶机制控制。短时间内可能允许少量突发请求，但请不要依赖“自然秒”边界进行并发控制。

当请求超过有效 RPS 时，接口将返回：

```json
{
  "code": 429,
  "message": "Rate limit exceeded",
  "data": null
}
```



:::highlight red 💡
触发 429 不会扣费。建议客户端采用退避重试策略，例如从 200～500ms 开始等待，并逐次增加等待时间，同时加入随机抖动；不要在短时间内无限重试。
建议将客户端并发数控制在当前账户或接口实际 RPS 范围内。对于耗时较长的接口，可保留较长的请求超时时间，但不要因客户端超时立即高频重复发起相同请求。
:::
## Support&Feedback/支持与反馈
如有任何疑问、定价详情、定制API，请随时通过我们的支持页面联系我们：

[联系我们](https://getoneapi.com/contact)