API 约定:Request ID、分页与错误
NextCLi API 的通用约定 —— 每条响应的 Request ID、列表分页参数与统一错误结构。
以下约定适用于 NextCLi 的各 API 接口。
Request ID
每条响应都带响应头 X-Request-ID。提交工单排障时附上它,可以帮助我们快速定位那次请求。
分页
列表接口使用 limit + offset 分页,时间字段为 UTC。各接口的默认与上限以实际响应为准。
错误结构
出错时响应体为 {"error": "..."},配合标准 HTTP 状态码:
| 状态码 | 含义 | | --- | --- | | 401 | 未认证 | | 403 | 无权限 | | 404 | 不存在 | | 422 | 参数或状态不符 | | 429 | 限流 |