错误处理

错误包络

所有 Token101 v1 路由在请求失败时都会返回顶层 error 对象。响应格式如下：

{
  "error": {
    "type": "invalid_request_error",
    "message": "Unsupported model",
    "code": "invalid_request_error"
  }
}

error 对象还带有一个 code 字段，它是 type 的镜像（取值相同），两者都可用于程序化分支。部分响应还会附带 detail 对象，提供更多上下文信息。客户端逻辑应优先围绕 error.type 建立，再把 message 作为给运维或终端用户展示的人类可读说明。

常见状态码

HTTP 状态码	Type	常见含义	建议动作
400	`invalid_request_error`	请求体未通过 schema 校验，或者请求的模型当前未启用。	修正 payload、字段名或 model ID 后再重试。
401	`authentication_error`	API Key 缺失、格式错误或校验失败。	发送 `Authorization: Bearer sk-...`，并轮换无效 key。
402	`insufficient_quota`	冻结或实际扣费的积分不足以覆盖本次调用。	充值积分，或把用户迁移到仍有余额的 plan。
403	`forbidden`、`account_suspended`、`permission_error`	账户、plan 或 upstream policy 阻止了请求。	检查计费状态、plan entitlement 和账户状态。
404	`not_found_error`	引用的资源未找到——例如 Responses API 中此前的 response id。	检查你引用的 id，而不是盲目重试。
429	`rate_limit_exceeded`	当前请求超过了策略窗口限制。	先遵守 `Retry-After`，再按 backoff 重试。
502	`upstream_error`	Token101 未能从上游模型服务商获取响应。	以幂等方式重试；若持续失败请联系客服。
504	`timeout_error`	AI 提供方未能及时响应。	使用有界超时并减少并发重试。
529	`overloaded_error`	模型服务商暂时过载。	稍作退避后再重试。

部分 429 响应使用旧版类型 rate_limit_error 而非 rate_limit_exceeded。请把两者当作同一种情况处理——在按 error.type 分支时把它们一并覆盖。

会话连续性（Responses API）

在 Responses API 中携带 previous_response_id 时，有两种不同的结果，它们返回不同的状态码。请按 detail.reason 区分：

HTTP 状态码	`detail.reason`	含义	建议动作
400	`responses_session_continuity_unavailable`	当前部署无法为该请求承载会话连续性。它不会被静默忽略——你会收到一个明确错误，而不是一个悄悄丢掉历史的 2xx。	去掉 `previous_response_id` 后重试，并把此前的对话轮次直接放进请求的 `input` 中。
404	`previous_response_not_found`	会话连续性可用，但你引用的具体 `previous_response_id` 不存在（已过期或 id 有误）。	检查你引用的 id，而不是盲目重试。

简言之：responses_session_continuity_unavailable 表示「把此前的轮次重新放进请求里」，而 previous_response_not_found 表示「你传的 id 有误」。未携带 previous_response_id 的单轮请求不受此影响。

Token 计数来源（count_tokens）

Anthropic 兼容的 count_tokens 预检通常返回上游的精确计数。如果无法取得该精确计数，Token101 会降级为本地估算，以便你的客户端继续工作。在降级路径上，响应会携带两个响应头，让你能区分「估算」与「精确计数」：

x-token101-count-tokens-source: local_estimate —— 返回的 input_tokens 是本地估算，而非上游精确计数。
x-token101-count-tokens-fallback-reason —— 使用估算的原因（例如 upstream_status_401）。

当计数为精确值时，这两个响应头都不会出现。可读取 x-token101-count-tokens-source 来决定是把计数当作权威值，还是留出保守余量。

实践建议

HTTP 状态码适合做粗粒度控制流，error.type 适合做程序化分支，而 detail.reason 在存在时可用于产品级提示。应将 400 和 401 视为客户端可修复问题，将 402/403/429 视为计费或访问限制，将 502/504 视为临时的提供方问题。条件允许时，把用户引导到速率限制或计费与积分页面，可以减少支持工单。

仍未解决？

如果按上述指引排查后错误仍然存在，发送邮件至 [email protected]，并尽量附上：

出现问题的大致时间与所用模型
完整的错误响应（JSON body）
响应头中的调用编号（如有）

我们会尽快回复。

错误包络

所有 Token101 v1 路由在请求失败时都会返回顶层 error 对象。响应格式如下：

{
  "error": {
    "type": "invalid_request_error",
    "message": "Unsupported model",
    "code": "invalid_request_error"
  }
}

常见状态码

HTTP 状态码	Type	常见含义	建议动作
400	`invalid_request_error`	请求体未通过 schema 校验，或者请求的模型当前未启用。	修正 payload、字段名或 model ID 后再重试。
401	`authentication_error`	API Key 缺失、格式错误或校验失败。	发送 `Authorization: Bearer sk-...`，并轮换无效 key。
402	`insufficient_quota`	冻结或实际扣费的积分不足以覆盖本次调用。	充值积分，或把用户迁移到仍有余额的 plan。
403	`forbidden`、`account_suspended`、`permission_error`	账户、plan 或 upstream policy 阻止了请求。	检查计费状态、plan entitlement 和账户状态。
404	`not_found_error`	引用的资源未找到——例如 Responses API 中此前的 response id。	检查你引用的 id，而不是盲目重试。
429	`rate_limit_exceeded`	当前请求超过了策略窗口限制。	先遵守 `Retry-After`，再按 backoff 重试。
502	`upstream_error`	Token101 未能从上游模型服务商获取响应。	以幂等方式重试；若持续失败请联系客服。
504	`timeout_error`	AI 提供方未能及时响应。	使用有界超时并减少并发重试。
529	`overloaded_error`	模型服务商暂时过载。	稍作退避后再重试。

部分 429 响应使用旧版类型 rate_limit_error 而非 rate_limit_exceeded。请把两者当作同一种情况处理——在按 error.type 分支时把它们一并覆盖。

会话连续性（Responses API）

在 Responses API 中携带 previous_response_id 时，有两种不同的结果，它们返回不同的状态码。请按 detail.reason 区分：

HTTP 状态码	`detail.reason`	含义	建议动作
400	`responses_session_continuity_unavailable`	当前部署无法为该请求承载会话连续性。它不会被静默忽略——你会收到一个明确错误，而不是一个悄悄丢掉历史的 2xx。	去掉 `previous_response_id` 后重试，并把此前的对话轮次直接放进请求的 `input` 中。
404	`previous_response_not_found`	会话连续性可用，但你引用的具体 `previous_response_id` 不存在（已过期或 id 有误）。	检查你引用的 id，而不是盲目重试。

Token 计数来源（count_tokens）

x-token101-count-tokens-source: local_estimate —— 返回的 input_tokens 是本地估算，而非上游精确计数。
x-token101-count-tokens-fallback-reason —— 使用估算的原因（例如 upstream_status_401）。

当计数为精确值时，这两个响应头都不会出现。可读取 x-token101-count-tokens-source 来决定是把计数当作权威值，还是留出保守余量。

实践建议

仍未解决？

如果按上述指引排查后错误仍然存在，发送邮件至 [email protected]，并尽量附上：

出现问题的大致时间与所用模型
完整的错误响应（JSON body）
响应头中的调用编号（如有）

我们会尽快回复。

错误包络

常见状态码

会话连续性（Responses API）

Token 计数来源（count_tokens）

实践建议

仍未解决？

目录

错误处理

错误包络

常见状态码

会话连续性（Responses API）

Token 计数来源（count_tokens）

实践建议

仍未解决？

目录