常见问题

client 返回 401

检查：

• 请求是否带了 Authorization: Bearer <user_token>。
• token 是否过期。
• City 是否配置了 DOWNCITY_FEDERATION_TOKEN_SIGNING_KEY。
• token 是否由当前 Federation 签发。
• token 中的 bureau_id 是否对应当前产品。

client 返回 403

检查：

• token 所属 Bureau 是否已经被暂停。
• 管理端签发 token 时，目标 Bureau 是否是 active。

client 返回 404

检查：

• 调用的 HTTP 路由是否正确。
• 目标 service 是否已经在 City 里注册。
• 管理端签发 token 时，目标 Bureau 是否存在。

模型不存在或没有命中 handler

检查：

• client 传入的 model 是否已通过 AIChannel.model() + AIService.use() 注册
• 目标 model 是否包含当前通路的 action，例如 text、stream 或 image。
• 请求里是否传入了预期的 model id。
• city.ai.catalog() 是否能看到这个 model。

这类问题通常会返回 422。

City 返回 500

检查：

• City 是否配置了 DOWNCITY_FEDERATION_TOKEN_SIGNING_KEY 并已通过 fed deploy 配置管理员账户。
• 目标 service 是否已经注册 handler。
• handler 或 provider 调用是否抛出了没有 statusCode 的错误。
• onError hook 是否记录了原始错误。

provider 调用失败

检查：

• City .env 是否存在对应 key。
• handler 是否通过 input.env() 读取了正确的 key。
• model meta 是否和当前 provider 调用方式匹配。

usage 没有记录

检查：

• AIService 和 CreditsService 是否先于 UsageService 挂载，并作为对应 Reader 传入。
• AI Provider 是否返回了最终 RuntimeMetering；没有最终计量时只增加执行次数。
• Credits 交易是否为已入账的正数 Charge；充值、失败或待处理交易不会计入消费。
• 查询是否传入真实、有序的 from、to 和有效 IANA timezone。