用途:帮助在集成 Hex API 时处理速率限制错误、实现重试逻辑并优化请求。Hex 对项目运行触发(RunProject)限制为每个 API 令牌每分钟 20 次、每小时 60 次;GetRunStatus、ListProjects、CancelRun 等读取操作无硬性限制。因此触发运行是集成架构的瓶颈,批量分析调度或 CI/CD 触发参数化笔记本时需管理每小时配额。
主要能力:提供令牌桶式 HexRateLimiter(同时维护分钟与小时令牌并排队等待)、带指数退避与抖动的重试函数 hexRunWithRetry(429 时按 30 秒×2^attempt 加随机抖动重试,5xx 时按 2^attempt×3 秒重试)、分批处理 batchRunProjects(默认批大小 5,批间等待 15 秒,轮询运行状态直至完成)。
使用方式:按项目与操作分类请求,分发前应用按作用域的并发限制;优先遵循服务端重试指引,否则使用有界指数退避加抖动并设最大尝试次数;变更类操作必须携带幂等键,不得重放运行、发布或调度变更;监控受限与延迟计数及金丝雀成功率,一次只调优一个作用域并保留回滚。
限制与注意:资料未提供具体价格、平台支持范围或官方 SDK 信息。常见问题包括 429(超触发限制,需排队并至少间隔 5 秒)、运行卡在 RUNNING(轮询最多 30 分钟后 CancelRun)、401(令牌轮换需刷新 CI 密钥)、空输出(项目无已发布输出)、409(同一项目并发触发)。输出速率限制回执时应排除查询文本、SQL、输出与凭据。