即使你的应用从未收到响应，请求也可能已经到达服务器。在开始重试发送之前，你的集成需要一套应对这种不确定性的策略。
Bird 的 REST SDK 为 TypeScript、Python、Go 和 PHP 提供了这种请求处理。Swift 和 Kotlin 包用于 Realtime 订阅，而非 REST API。
Bird SDK 处理哪些事务？
SDK 处理可重复的请求机制，包括重试、路由和去重保护。
对于变更操作，它会生成一个 Idempotency-Key 并在内部重试中保持不变。这使 Bird 能够在响应丢失后识别同一操作。
它使用遵循 Retry-After 的退避策略重试瞬时故障。因此 429 会导致在下一次尝试前等待。身份验证和校验失败仍需你的应用纠正其原因。
列表辅助方法在你迭代时逐页获取数据。区域路由根据密钥前缀选择主机。Webhook 辅助方法在返回解码后的事件之前验证原始请求体。
你的应用仍然需要拒绝重复的业务操作，也需要恢复自身未完成的工作。幂等性解释了请求重试与应用层保证之间的边界。
如果我的操作没有对应的类型化方法怎么办？
使用 SDK 的 HTTP 动词方法来调用没有专属类型化方法的公开端点。
这些方法保留了请求处理能力，包括重试和区域选择。你从 API 参考文档中获取路径和载荷。
缺少类型化方法不代表操作不可用。改变调用方式不会改变你的凭据能访问哪些端点。
例如，通过已登录的 CLI 或 MCP 会话轮换 API 密钥，或使用控制面板。CLI 或 MCP 服务器需要具有 api_keys:write 的用户授权。仅持有 API 密钥的服务无法执行此操作。
什么时候应该直接调用 HTTP？
当可用的 SDK 不适合你的语言、运行时或依赖策略时，直接调用。
你也可以使用直接请求在选择客户端库之前检查端点。Bird 对两种方式使用相同的公开 HTTP API。
如果你希望在其他语言中使用生成的模型，可以从 OpenAPI 规范生成客户端。需要单独检查其运行时行为，因为不同的生成器实现的功能各有不同。
对于直接请求，根据密钥所属区域选择主机。在同一操作的多次重试中复用同一幂等键。跟随分页游标。在未更改的请求体上验证传入的 webhook 签名。
设置重试和超时限制，以防失败的依赖项使应用请求无限期挂起。
重试如何影响我的超时？
重试会使总调用时间超过单次尝试的超时。
SDK 默认允许两次重试，因此一次调用最多有三次尝试。TypeScript、Python 和 Go 的默认超时为每次尝试 60 秒。三次全部超时的尝试在加上重试等待之前就可能消耗约三分钟。
PHP 使用你注入的 HTTP 客户端上配置的超时。在那里设置它，以确保请求有一个有限的持续时间。
根据外部截止时间调整重试预算。SDK 概念指南描述了每种语言的配置名称和按调用覆盖的方式。
不要在 SDK 外层添加无限重试循环。独立的 SDK 调用会生成不同的键，除非你为整个操作提供一个固定的幂等键。
我应该选择哪种集成方式？
选择你的应用需要自行承担的最少请求处理量。
- Bird SDK: 你的语言受支持，且其依赖项适合你的运行时。
- SDK verb method: 操作是公开的，但缺少专属类型化方法。
- Generated client: 你需要其他语言或自己的生成约定。
- Direct HTTP: 你希望控制依赖项并自行实现请求策略。
简而言之
SDK 处理重复的请求管道。
它们管理幂等键、重试、区域路由、分页和 webhook 验证。你的应用仍然负责自身的业务规则。
缺少类型化方法不会阻碍你。
使用 SDK 的 HTTP 动词方法来调用其类型化接口之外的公开操作。请求处理仍然适用。
在应用重试中保持同一个键。
独立的 SDK 调用会生成不同的幂等键，除非你自行为该操作提供键。
为每次尝试预留时间预算。
默认启用两次重试。TypeScript、Python 和 Go 为每次尝试单独设置超时。PHP 使用其 HTTP 客户端的超时。