API速率限制和最佳实践

每个Ody API密钥在/v1/api/*和MCP端点上每分钟可获得600个请求——请阅读每个响应中的RateLimit-*标头，并在收到429错误时使用Retry-After值进行退避。

限制的工作原理

• 限制是按密钥计算的，在一个固定的60秒窗口内。没有有效密钥的请求则按IP进行限制。
• 每个响应——无论是成功还是错误——都带有三个标准标头：
  • RateLimit-Limit — 您的每分钟预算（600）。
  • RateLimit-Remaining — 当前窗口中剩余的请求数。
  • RateLimit-Reset — 窗口重置前的秒数。
• 超出限制将返回429错误，错误代码为resource_exhausted，并带有Retry-After标头（秒）。在重试之前，请至少等待该时间。

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 600
RateLimit-Remaining: 0
RateLimit-Reset: 23
Retry-After: 23

保持在限制内

• 关注RateLimit-Remaining，并在其接近零时主动放慢速度，而不是等到收到429错误才做出反应。
• 使用webhook而不是轮询。 将一个端点订阅到message.received等事件，Ody会将活动推送到您——请参阅接收webhook并验证签名。如果您必须轮询，对于共享收件箱来说，每10-30秒一次就足够了。
• 在遇到429和5xx错误时，使用指数退避和抖动进行重试，并限制重试次数。如果存在Retry-After，请遵循其指示。对于发送操作，将重试与Idempotency-Key配对，以避免重复发送——请参阅分页、幂等性和错误处理。
• 在同步数据时，请求更大的页面（?limit=最大可达每个端点的限制），而不是许多小页面。

密钥安全最佳实践

• 将每个密钥的权限范围限制在所需的最小程度。 在创建时取消选择不必要的范围——一个只读取对话的仪表板应该只拥有conversations:read权限。请参阅获取您的Ody API密钥。
• 在任何真实短信发送会成为错误的地方使用测试密钥。 开发环境和CI应该使用ody_test_…密钥运行，以便模拟消息发送——请参阅使用测试模式安全构建。
• 每个集成一个密钥。 为Zapier、您的服务器和AI助手使用单独的密钥意味着您可以撤销其中一个而不会影响其他，并且设置 → 开发者API中的“上次使用”列仍然有意义。
• 将密钥保存在服务器端。 切勿将密钥嵌入到移动应用程序、浏览器JavaScript或共享文档中——任何拥有密钥的人都可以在其权限范围内充当其创建者。
• 轮换和修剪。 撤销您不再使用的密钥。由于明文只显示一次，轮换意味着创建一个新密钥，部署它，然后撤销旧密钥。

相关文章

• API概述和身份验证
• 分页、幂等性和错误处理
• 接收webhook并验证签名
• 使用测试模式安全构建