速率限制和 API 错误

Telemetry 端点使用标准 HTTP 状态代码。在重试之前，客户端应将请求缺陷与临时服务或容量状况区分开来。

计划特定的配额和当前限制可能会发生变化。将产品和计费设置中显示的限制视为帐户的真实来源；不要对未记录的全局请求率进行硬编码。

反应等级

错误主体可能包括更具体的上下文。记录状态、端点名称、请求 ID 和安全错误类别。不要仅仅因为请求失败就记录 API 密钥或原始事件负载。

使用 anon_… 密钥时，除 HTTP 状态外，还要读取 JSON 中的 code。403 不一定表示密钥错误，并非所有 429 都能通过等待解决。

错误码	状态	处理方式
`anonymous_signup_required`	`403`	首个事件发送后 24 小时的匿名读取窗口已结束。使用响应中的私密 `signup_url` 将现有工作空间关联到账号并保留数据。不要更换密钥或新建试用来找回这些事件。
`anonymous_account_required`	`403`	此功能需要账号。关联试用后继续使用原工作空间。
`anonymous_rate_limited`	`429`	等待后重试，并限制重试次数、逐步延长等待时间。
`anonymous_table_limit` 或 `anonymous_free_limit`	`429`	试用的表数量或用量额度已耗尽。关联工作空间并检查账号限制；仅等待不会恢复试用额度。
`anonymous_invalid_batch`	`413`	缩小批次，并根据响应消息检查表名后再重试。
`anonymous_expired`	`410`	未关联的试用已过期，无法再通过关联恢复。使用账号重新开始；不要继续用此密钥重试。

关联链接属于私密信息：不要在公开工单或日志中记录 signup_url。在其他浏览器中，打开关联页面，使用输入现有匿名 API 密钥的选项来关联原试用。关联会保留工作空间和密钥。

对 429、502、503 和 504 响应使用带抖动的指数退避。限制尝试和总运行时间，以便遥测中断不会耗尽应用程序工作人员的精力。

delay = min(max_delay, base_delay * 2^attempt) + random_jitter

在不修改请求的情况下，请勿重试 400 响应。重复发送无效架构或 SQL 查询会创建负载，但不会创建成功路径。

重试摄取时，请为逻辑事件重新使用稳定的 event_id。这使得重复传递变得可测量，并允许幂等消费者识别重试。每次网络尝试上的新标识符都会将一个结果转变为几个无法区分的业务事件。

使用重复的事件 ID 配方审核重试行为。

确定遥测是否位于关键路径上。对于大多数产品仪器，应通过安全诊断通道报告临时摄取失败，而不更改已成功的客户响应。对于合规性或计费工作流程，持久队列可能比较合适。

对于大型结果集，请使用异步查询API，而不是重复重试交互式请求。有关范围规则，请参阅 API 密钥与身份验证。