请求与错误

地址与格式

所有接口都在 https://api.sealreply.com/v1 下，收发 JSON（Content-Type: application/json）。时间是 UTC 的 ISO 8601 格式。ID 都是 UUID，消息 ID 按时间先后排序。

每个响应都包在同一个结构里：

{ "success": true, "data": { … }, "error": null }

错误

失败时 success 为 false，data 为 null，error 说明原因：

{
  "success": false,
  "data": null,
  "error": {
    "code": "validation_failed",
    "message": "Some fields are invalid. Please check and try again.",
    "fields": { "email": "invalid" },
    "request_id": "req_01a1…"
  }
}

程序请按 code 判断；message 是给人看的，语言跟随 Accept-Language 请求头。联系我们时请附上 request_id。

错误码	状态码	含义
bad_request	400	请求无法解析
validation_failed	422	某个字段不合法，fields 说明是哪个、为什么
unauthorized	401	没带 Key、Key 不存在或已吊销
forbidden	403	Key 缺少权限（fields.scope），或该接口不对 Key 开放
tenant_suspended	403	工作区已被暂停
not_found	404	你的工作区里没有这个资源
conflict	409	数据已被修改，或同一个 Idempotency-Key 的请求还在处理
conversation_closed	409	会话已结束
rate_limited	429	请求太频繁，等 Retry-After 秒后再试
quota_exceeded	402	达到套餐限额，fields.limit 说明是哪项
plan_upgrade_required	402	套餐不含该功能，fields.feature 说明是哪个
internal	500	我们这边出错，可以安全重试

分页

列表接口最多返回 limit 条（默认 20，最大 100），并附带游标：

{ "data": [ … ], "meta": { "has_more": true, "next_cursor": "MjAyNi0…" } }

传 cursor=<next_cursor> 取下一页，直到 has_more 为 false。会话列表按最近活动倒序；消息历史从最新的往前翻。

安全重试

• 发消息：每条消息带一个你生成的 client_msg_id（UUID 即可）。用同一个值重发会返回第一次的那条消息，不会重复。
• 任何写操作：带上 Idempotency-Key 请求头（最长 255 字符）。24 小时内重复同一请求，会返回第一次的成功响应，并带 Idempotent-Replayed: true。同一个 Key 用于不同的请求体会返回 422（fields.Idempotency-Key = reused）；第一次还在处理时重复请求会返回 409 conflict。失败的响应不会被保存，可以直接重试。

不认识的字段

响应和 Webhook 内容以后可能增加新字段和新的枚举值。遇到不认识的请忽略，不要因此报错。