错误码

业务 API 使用统一信封。失败时 meta.credits_charged 恒为 0（不计费）。

HTTP	code	说明	计费
400	40001	参数错误	否
401	40101	缺少 / 无效 Key	否
402	40201	余额不足	否
403	40301	IP / scope	否
404	40401	端点或资源不存在	否
422	42201	质量门槛失败	否
429	42901	限流	否
500	50001	内部错误 / 成本护栏	否
502	50201 / 50202	上游错误 / SCHEMA_MISMATCH	否
503	50301 / 50302	维护 / 无可用路由	否
504	50401	上游超时	否

成功：code = 0，HTTP 200。

排查 request_id

每次响应（含失败）都带 X-Request-Id 响应头，或在 JSON meta.request_id 中返回。

1. 登录控制台 → 请求日志（/console/logs）

2. 粘贴 request_id 搜索

3. 查看「为何不计费」与失败规则

4. 仍无法解决：联系支持并附上 request_id

42201 · 质量门槛

当上游返回 200 但关键字段为空、或不符合 workflow 质量规则时触发。不计费。

示例响应：

{
  "code": 42201,
  "message": "quality",
  "data": null,
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "endpoint": "xiaohongshu.note.detail",
    "credits_charged": 0,
    "failed_rule": "required_field:author.id",
    "elapsed_ms": 412
  }
}

常见成因： 参数指向不存在或已删除的资源；上游临时返回空壳。

下一步： 换有效参数重试；在请求日志中核对 failed_rule；携带 request_id 联系我们。

40101 · 无效 Key

{
  "code": 40101,
  "message": "Invalid or revoked API Key",
  "message_zh": "API Key 无效或已吊销",
  "data": null,
  "meta": {
    "request_id": "…",
    "credits_charged": 0
  }
}

下一步： 确认使用完整密钥（非前缀）；在控制台重新创建 Key。

40201 · 余额不足

下一步： 控制台 → 账单流水 → 充值；确认 meta.credits_balance。

42901 · 限流

下一步： 降低 QPS 或联系商务提升配额。