分页、幂等性和错误处理

Ody API 在其列表端点上使用不透明游标分页，使用 Idempotency-Key 标头进行安全的消息发送重试，并在每个响应中提供一个带有请求 ID 的统一错误封装——本指南涵盖了这三点。

游标分页

GET /v1/api/contacts 和 GET /v1/api/conversations 使用 ?limit= 和 ?cursor= 进行分页：

curl "https://api.ody.co/v1/api/contacts?limit=100" \
  -H "Authorization: Bearer ody_live_…"

响应包含一个 nextCursor ——将其作为 ?cursor= 传回以获取下一页，并在其为 null 时停止：

{ "contacts": [ … ], "nextCursor": "eyJ…" }

• 游标是不透明的——始终按原样传回；修改或过期的游标会返回 400 invalid_argument。
• 页面大小限制：联系人默认 50，最大 200；对话默认 50，最大 100。GET /v1/api/messages/search（默认 25，最大 100）和 GET /v1/api/calls（默认 50，最大 200）仅接受 ?limit=，不带游标。
• 官方 SDK 会通过 listAll() / list_all() 为您跟踪 nextCursor ——请参阅SDK 快速入门：TypeScript 和 Python。

幂等消息发送

在您 POST /v1/api/messages 后发生的网络故障会让您不知道短信是否已发出——盲目重试有双重发送的风险。发送一个 Idempotency-Key 标头（任何字符串，最长 200 个字符，每个逻辑发送唯一），重试就会变得安全：

curl https://api.ody.co/v1/api/messages \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{"to":"+15125550123","body":"Your order shipped!"}'

• 第一次成功的响应会存储 24 小时；在该时间窗内使用相同键的任何重试都会原样重播该响应，而不是再次发送，并带有 Idempotency-Replayed: true 响应标头。
• 从您自己的业务事件（例如“order-1042-shipped”）派生键，而不是每次尝试都使用随机值——关键在于重试共享它。

错误封装

每个错误响应都使用相同的结构：

{ "error": { "code": "permission_denied", "message": "This API key is missing the 'messages:send' scope", "requestId": "req_…" } }

状态	代码	处理方式
400	invalid_argument	修复请求——消息会说明问题所在
401	unauthenticated	密钥缺失、无效或已撤销。不要重试；通知集成所有者
403	permission_denied	消息会指出缺失的范围——创建一个具有该范围的密钥
404	not_found	此工作区中不存在该资源
409	failed_precondition	工作区尚无法执行此操作（例如，没有可用于发送的活动号码）。将其显示出来，不要重试
429	resource_exhausted	速率受限——等待 Retry-After 秒，然后使用指数退避重试
500	internal	使用指数退避和抖动重试；限制重试次数

请求 ID

每个响应——无论是成功还是错误——都带有一个 X-Request-Id 标头，并在错误正文中作为 requestId 回显。将其与您自己的请求日志一起记录，并在联系支持时引用它：它能精确指出我们这边的请求。您还可以提供自己的 X-Request-Id（最多 64 个字符，字母/数字/_/-），Ody 会将其回显，这使得关联重试变得容易。

相关文章

• API 概述和身份验证
• API 速率限制和最佳实践
• SDK 快速入门：TypeScript 和 Python