认证与请求头
本页说明公开 API 的 Base URL、API 密钥认证、请求追踪 ID，以及契约中已声明但当前尚未实现的请求头。
1. Base URL 与请求格式
| 项目 | 取值 |
|---|---|
| Base URL | https://api.sequenxai.com/v1 |
| 已开放端点 | POST /v1/forecast、POST /v1/clean |
| 请求体 | UTF-8 JSON 对象；无法解析返回 400 MALFORMED_JSON，不是对象返回 422 VALIDATION_ERROR |
| 响应体 | JSON；错误统一使用 {"error": {...}} 信封，见错误码与排障 |
OpenAPI 中的 /anomaly-detection、/batch/forecast、/batch/jobs/{job_id} 与 https://api.sequenxai.com/cn/v1 前缀尚未开放；前三个操作在 OpenAPI 参考中标为「暂未开放」（x-availability: planned），调用返回 404。
2. API 密钥
每个请求都要携带租户密钥：
Authorization: Bearer sqx_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX密钥在 SequenxAI 平台 platform.sequenxai.com 的「API 密钥」页创建，完整明文只在创建时显示一次。服务端只保存密钥的摘要，无法找回；遗失后在「API 密钥」页删除并重新创建即可。删除立即生效且无法撤销，之后使用该密钥的请求返回 401，列表中也不再显示它（用量页仍按原名称归属其历史用量）。
| 情况 | HTTP | error.code |
|---|---|---|
缺少 Authorization、格式不是 Bearer <key>、密钥不存在、已删除或已被吊销 | 401 | INVALID_API_KEY（响应头带 WWW-Authenticate: Bearer） |
使用 sqx_test_* 测试密钥 | 401 | INVALID_API_KEY：真实 API 只接受 sqx_live_* |
密钥缺少 forecast:write 权限范围 | 403 | INSUFFICIENT_SCOPE：在平台创建的密钥默认带此范围 |
| 密钥所属账号或工作区被 SequenxAI 停用（Beta） | 403 | ACCOUNT_SUSPENDED：密钥本身仍有效，恢复后即可再用；请联系支持 |
| 密钥所属工作区处于删除冷静期（Beta） | 403 | ORG_PENDING_DELETION：在平台撤销删除后密钥恢复可用 |
3. 请求 ID
服务端为每个请求（包括失败的请求）生成一个 req_… 形式的 ID，同时出现在：
- 响应头
X-Request-Id； - 成功响应体的
request_id，或错误响应体的error.request_id。
联系支持时请提供这个 ID。
你也可以在请求头 X-Request-Id 中传入自己的追踪 ID。它必须匹配 ^[A-Za-z0-9_-]{8,64}$，匹配时会原样回显在响应头 X-Client-Request-Id 中，并随用量记录保存；不匹配时被静默忽略、不回显。你的 ID 只用于关联日志，不会替代服务端 ID，也不会被当作幂等键。
4. 请求头一览
| 请求头 | 状态 | 说明 |
|---|---|---|
Authorization | 必填 | Bearer sqx_live_… |
Content-Type | 建议 | application/json |
X-Request-Id | 可选 | 你的追踪 ID，规则见上一节 |
Idempotency-Key | 可选 | 仅 /v1/forecast：1–255 个可打印 ASCII 字符，按 API 密钥隔离，保留 24 小时，规则见下方说明。旧的 X-Idempotency-Key 作为已弃用别名再保留一个版本 |
X-SequenX-Region | 尚未读取 | 契约预留的区域提示，当前不影响路由 |
5. 响应头一览
| 响应头 | 何时出现 | 说明 |
|---|---|---|
X-Request-Id | 始终 | 服务端生成的 req_… |
X-Client-Request-Id | 你传入了合法的 X-Request-Id | 回显你的追踪 ID |
Retry-After | 429；503 MODEL_BUSY；服务暂停或清洗容量已满时的 503 SERVICE_UNAVAILABLE | 建议等待的秒数 |
X-RateLimit-Limit / -Remaining / -Reset / -Limit-Type / -Policy | 密钥通过认证后的每个响应 | 平时描述该密钥所属账号的每分钟请求数限制（账号下所有密钥共用）；429 时描述被耗尽的那个桶。见计量、额度与限流 |
X-Idempotent-Replayed | 幂等重放 | 固定为 true：本响应是同一幂等键首次请求保存下来的结果 |
Deprecation | 只传了 X-Idempotency-Key | 固定为 @1791417600（RFC 9745 日期格式，即自 2026-10-08T00:00:00Z 起弃用）：请改用 Idempotency-Key |
WWW-Authenticate | 401 | 固定为 Bearer |