API 指南

错误与限流

先分类,再重试

应用必须区分请求、身份、策略、配额与瞬时上游失败。盲目重试所有非 200 响应只会放大成本和事故。

错误分类

请求格式和认证失败需要调用方修正;策略和配额失败需要运营决策;只有明确分类为瞬时上游失败的情况才适合重试。


限流

若响应包含 Retry-After 必须遵守,并使用带抖动的退避;所有尝试都要受同一个应用 Deadline 约束。工作区和 Service Key 限额可能同时生效。


关联信息

记录 HTTP Status、结构化 Error Type、Router Request ID、路由类别和终态;日常日志中不得包含凭据或内容。


流式失败

输出前失败可能允许 Router Fallback;输出开始后的失败必须以 incomplete 终态或应用可见恢复处理,不能把第二家 Provider 的响应暗中拼接进去。