#响应、错误与幂等

#成功响应

{
  "code": "OK",
  "message": "success",
  "data": {},
  "request_id": "01900000-0000-7000-8000-000000000001"
}

request_id 应贯穿客户端错误上报、服务端日志和审计排障。

#错误响应

{
  "error": {
    "code": "IAM.AUTH.INVALID_CREDENTIALS",
    "message_key": "errors.iam.auth.invalid_credentials",
    "message": "账号或密码错误",
    "details": {}
  },
  "request_id": "01900000-0000-7000-8000-000000000001"
}

客户端只根据稳定 error.code 或 message_key 判断业务，不解析 message。常用 HTTP 状态：

#语言协商

请求使用 Accept-Language: zh-CN 或 en-US，响应使用 Content-Language。错误码与原始数据不随语言改变。

#分页

Admin 资源常用 page / page_size，移动消息和文章使用 opaque cursor。客户端不得解析 cursor 内容，也不能在同一资源上擅自混用分页模式。

#幂等与重试

GET / HEAD 可以在网络中断后有限退避；POST / PATCH / DELETE 默认不重试。只有 OpenAPI 明确支持 Idempotency-Key 的写操作才可安全重放：

Idempotency-Key: 01900000-0000-7000-8000-000000000001