分销商 API 认证与限额
OneProvider 分销商 API 的 Bearer 令牌、权限范围、IP 白名单、速率限制、错误码、幂等键和分页，附示例。
分销商 API 的 Bearer token、权限、IP 允许列表、速率限制、错误码、幂等键和分页。
全部模型、功能与价格 面向 AI 智能体的文档索引：https://oneprovider.dev/docs/llms.txt Token
token 以 rsk_ 开头，后面跟 40 个字符。在个人中心（“分销商”栏目的“API 与设置”）创建；其值只显示一次，我们只保存哈希值和最后 4 个字符。您最多可有 10 个有效 token，并可随时撤销其中任何一个。创建 token 时可以设置有效期（1 到 365 天）：到期后该 token 返回 401 token_expired，GET /me 中的 expires_at 会告诉您到期时间（null 表示永久有效）。
httpAuthorization: Bearer rsk_...权限（scope）
一个 token 带有一组权限。各项权限相互独立：keys 并不包含 read。GET /me 对任何有效 token 都可用。缺少所需权限时，响应为 403 forbidden_scope。
| Scope | 可以做什么 |
|---|---|
read | 读取：余额与交易、价格、模型、客户、密钥及其用量、订单、套餐、统计、店铺设置 GET /settings、操作日志 GET /audit（除兑换码、Webhook、机器人、支付方式和充值支付状态外的所有 GET）。 |
keys | 写入：客户（包括封禁）、发放、编辑、暂停、充值、重新发放和删除密钥，POST /orders，店铺设置 PATCH /settings（它们决定已发放密钥的外观）。 |
codes | 兑换码批次及兑换码本身（读取、创建、作废、兑换）。兑换码属于机密，因此单独设一项权限。 |
plans | 创建、编辑和删除套餐（读取套餐需要 read）。 |
billing | 为分销商余额充值：POST /balance/topups 及支付状态。 |
webhooks | 管理 Webhook、发送测试、读取投递日志。 |
support | 为即将推出的客服接口预留。 |
bot | 读取机器人和支付方式的状态：GET /bot 和 GET /payment-providers（响应中不含 token）。机器人只能在个人中心连接。 |
每个方法所需的权限列在参考 中。
IP 允许列表
可以把 token 限制在一组 IPv4/IPv6 地址或 CIDR 网段内（最多 20 项）。来自其他地址的请求会返回 403 ip_not_allowed。该列表在创建 token 时设置。
速率限制
每个 token 每秒 20 个请求，每个来源 IP 地址每秒 100 个请求。超出时返回 429 rate_limited 和 Retry-After 响应头。请等待相应的秒数后重试。
错误
每个错误的结构都相同。相同的 id 也会通过 X-Request-Id 响应头返回：联系客服时请附上它。
{
"error": {
"code": "insufficient_balance",
"message": "Not enough free reseller balance for this key.",
"request_id": "req_..."
}
}请根据 error.code 判断，不要依据消息文本。
| HTTP | code | 含义 |
|---|---|---|
| 400 | invalid | 缺少字段，或字段值超出范围。 |
| 400 | bad_request | 无法解析请求。 |
| 400 | idempotency_key_required | 会动用资金的方法缺少 Idempotency-Key 请求头。 |
| 400 | invalid_url | Webhook URL 未通过校验（仅限 https，不允许 IP 字面量或内网地址）。 |
| 400 | limit_below_spent | 密钥的新额度低于它已经消耗的金额。 |
| 400 | currency_required | POST /balance/topups：该支付服务商支持多种币种，请传入 currency（可用的币种见 topup_providers）。 |
| 400 | method_unavailable | POST /balance/topups：topup_providers 中没有这个支付服务商（币种或邮箱有误时，同样会返回 bad_currency、bad_email 或 email_required）。 |
| 401 | unauthorized | token 缺失、未知或已撤销。 |
| 401 | token_expired | token 已过期（见 GET /me 中的 expires_at）：请创建新的 token。 |
| 403 | forbidden_scope | token 缺少所需的权限。 |
| 403 | ip_not_allowed | 请求的 IP 不在 token 的允许列表中。 |
| 403 | reseller_disabled | 该分销商已失去访问权限；其所有 token 都会返回此错误。 |
| 403 | banned | 账户已被封禁。 |
| 404 | not_found | 该对象不存在，或属于其他分销商。 |
| 404 | key_not_found | 密钥不存在。 |
| 409 | insufficient_balance | 金额超出“可用”（Free，即 available_usd），见资金规则。 |
| 409 | idempotency_key_reused | 相同的 Idempotency-Key 已用于另一个不同的请求体：请使用新的幂等键。 |
| 409 | fund_first | 请先为分销商余额充值。 |
| 409 | not_activated | 分销商中心尚未开通。 |
| 409 | name_taken | 已存在同名密钥。 |
| 409 | key_limit | 密钥数量已达上限。 |
| 409 | plan_limit | 套餐数量已达上限（20 个）。 |
| 409 | customer_limit | 客户数量已达上限（10,000 个）。 |
| 409 | plan_in_use | 只要还有一张未过期的未支付账单，或一笔已付款但尚未交付的机器人购买在使用某个套餐，就不能删除该套餐、提高其价格或改用其他币种。 |
| 409 | key_exhausted | 重新发放：密钥已没有可转移的余额，剩余为 0。 |
| 409 | key_expired | 重新发放：密钥已过期，请先延长有效期。 |
| 409 | action_failed | 密钥操作因其他原因失败；请重试或检查该密钥。 |
| 409 | code_used | 该兑换码已被兑换。 |
| 409 | code_revoked | 该兑换码已作废。 |
| 409 | code_busy | 该兑换码正在处理中，或现在无法兑换。 |
| 409 | external_order_id_conflict | 该 external_order_id 已被使用，且参数不同。 |
| 409 | customer_exists | 已存在使用该 external_id 的客户。 |
| 409 | customer_blocked | 该客户已被封禁：针对该客户的密钥、订单和兑换都会被拒绝。 |
| 409 | token_limit | 有效 token 数量已达上限（10 个）。 |
| 409 | webhook_limit | Webhook 数量已达上限（5 个）。 |
| 429 | rate_limited | 每个 token 每秒超过 20 个请求（或每个 IP 地址每秒超过 100 个）；请等待 Retry-After 指定的秒数。 |
| 429 | too_many_invoices | POST /balance/topups：连续未支付的账单过多；请先支付未结账单，或一分钟后重试。 |
| 501 | sandbox_not_implemented | 沙盒（rsk_test_...）尚未实现。 |
| 503 | provider_unavailable | 支付或模型服务商暂时不可用：请稍后重试。 |
幂等性
会动用资金的方法必须带 Idempotency-Key 请求头（1 到 128 个可打印字符）；缺少它（或格式不合适）时，响应为 400 idempotency_key_required。参考中已标出这些方法。使用相同的幂等键和相同的请求体（按分销商）重复请求，绝不会重复动用资金，并会返回同一个对象，包括该次调用所生成密钥的 secret：响应在途中丢失时，重复调用即可取回。相同的幂等键搭配不同的请求体会返回 409 idempotency_key_reused。每笔新的支付或订单都要使用新的幂等键；对 POST /orders 来说，标识是 external_order_id。该请求头在 PATCH /keys/{id}（重复的 extend_days/extend_hours 只会延长一次）、POST /plans 和 POST /webhooks（重复调用返回同一个对象；不会再次显示 Webhook secret）上是可选的（带上时会生效）。
curl -s -X POST https://app.oneprovider.dev/partner/v1/keys \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"name":"client-1","limit_usd":"10.00"}'请把幂等键和您自己的订单记录一起保存，这样网络出错后，您就能重试完全相同的请求。
分页
列表接口接受 ?limit=1..100（默认 50）和 &cursor=。响应为 {"items": [...], "next": "<cursor>"}；最后一页的 next 为 null。cursor 是不透明的：原样传回即可。
curl -s "https://app.oneprovider.dev/partner/v1/keys?limit=100&cursor=<next from the previous page>" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"沙盒
测试 token rsk_test_... 即将推出。目前这类 token 会返回 501 sandbox_not_implemented。