开始使用
错误码
所有失败都是 { error: { code, message, params }, meta };按 code 分支处理。下表按排查频率排序。
机器码对照表
| code | HTTP | 含义 | 怎么处理 |
|---|---|---|---|
| unauthenticated | 401 | 没带 Bearer 凭证、凭证无效、已停用、已过期,或不是长期凭证(popkit_it_ 开头)。 | 到设置页「接入外部系统 → 长期凭证」检查状态或重新签发;请求头写 Authorization: Bearer <凭证>。 |
| forbidden | 403 | 凭证缺少该端点要求的 scope,或签发者在工作区里的角色不允许这个动作,或请求的发布落点不在凭证的白名单里。params 里带 scope / action。 | 重新签发一枚带对应 scope / 落点的凭证;角色问题找工作区管理员。 |
| workspace_not_found | 403 | 凭证绑定的工作区已解散,或签发者已不是该工作区的有效成员 / 已被封禁。 | 由仍在工作区内的管理员重新签发凭证。 |
| not_found | 404 | 目标对象不存在或不属于本工作区(不区分两者,防枚举)。 | 用列表端点重新取 id;不要拿 replyRowId 当 commentId 用。 |
| invalid_input | 400 | 入参不合法:缺必填、枚举值不对、时间没带时区、游标坏了、发布档没带 Idempotency-Key 等。message 里列出具体字段。 | 按 message 修正后重试;同一个 Idempotency-Key 可以复用(失败不会被缓存)。 |
| plan_limit | 402 | 套餐配额耗尽(本月定时发布条数等)。params 带 limit / used。 | 先用 GET /v1/workspace 看余量;等下月或升级套餐。 |
| no_account | 409 | 目标平台在本工作区没有可用账号。 | 让用户在站内「渠道账号管理」连接账号;外部系统无法代劳。 |
| needs_reauth | 409 | 目标账号的平台授权已失效。 | 让用户回站重新授权;GET /v1/accounts 的 status 为 expired 的就是它。 |
| rate_limited | 429 | 本凭证在该档位的调用超过了每分钟上限,或触发了发布 / 评论回复的日上限、单账号最小间隔。params 带 limit / windowSec / retryAfterSec 或 reason。 | 按 Retry-After 头等待后重试;日上限类的 reason 重试无用,等次日。 |
| replay | 409 | 带同一个 Idempotency-Key 的请求仍在处理中。 | 稍等后重试同一个键;已完成的会原样回第一次的结果并带 meta.replayed: true。 |
| external_writes_off | 503 | 当前环境关闭了对外写入(测试环境安全阀),发布 / 回复不会真正外发。 | 这是环境配置,不是入参问题;在生产环境调用。 |
| platform_error | 502 | 平台侧拒绝或失败(政策、判重、5xx)。params.reason 带机器码。 | 用 GET /v1/posts/{postId} 看逐账号的 errorCode;重试请走 POST /v1/posts/{postId}/publish。 |
| internal | 500 | 未归类的服务端错误,已记日志。 | 带上响应里的 meta.requestId 联系我们。 |
示例
{
"error": {
"code": "rate_limited",
"message": "rate limit exceeded for tool create_post (write): 10 calls per 60s",
"params": {
"limit": 10,
"windowSec": 60,
"retryAfterSec": 42
}
},
"meta": {
"requestId": "3f9c1e2a-7d4b-4c1e-9a6f-0b2d8e5c7a19"
}
}