一次请求的处理流程
本页从调用方的角度说明一次 /v1/forecast 请求依次经过哪些阶段、每个阶段可能返回什么。逐项检查顺序见 POST /v1/forecast。
1. 各阶段
每个请求都按顺序经过以下检查，通过则进入下一阶段；「不通过时返回」中的错误只在该步不通过时返回。
| 阶段 | 做什么 | 不通过时返回 |
|---|---|---|
| 认证 | 校验 Authorization: Bearer sqx_live_… 与权限范围，再确认接口未被暂停、密钥所属账号或工作区正常，满足则继续。 | INVALID_API_KEY、INSUFFICIENT_SCOPE、ACCOUNT_SUSPENDED、ORG_PENDING_DELETION、503 SERVICE_UNAVAILABLE（接口暂停，带 Retry-After） |
| 幂等 | 传了 Idempotency-Key 时登记该键；同键同体且已完成的请求直接返回保存的结果（不重复计费）。 | VALIDATION_ERROR（400）、IDEMPOTENCY_KEY_REUSED、IDEMPOTENCY_IN_PROGRESS |
| 限流检查 | 把本次请求计入账号本分钟的请求数（账号下所有密钥共用），未超出上限则继续。 | 429 forecast-rpm |
| 请求校验 | 解析 JSON，检查字段、单次行数上限（200,000 行；超大请求直接拒绝，不排队）与清洗选项，合法则继续。 | MALFORMED_JSON、VALIDATION_ERROR、POINTS_EXCEEDED、CLEANING_OPTION_UNSUPPORTED |
| 模型选择 | 确认模型可用、h 不超过最大步长、没有实体长于最大上下文，满足则继续。 | MODEL_NOT_AVAILABLE、MODEL_OPTION_UNSUPPORTED、HORIZON_EXCEEDS_MODEL、SERIES_TOO_LONG、SERVICE_UNAVAILABLE |
| 额度预占 | 按「行数 + h × 实体数」预占今天的点数，剩余额度足够则继续。 | 429 forecast-daily-points |
| 清洗 | 按生效的预设整理数据并生成清洗报告（raw 预设只做结构校验），通过则继续。清洗容量满时先短暂排队。 | SERIES_DISCONTINUOUS、TIMESTAMP_IRREGULAR、FREQ_*、SERIES_TOO_SHORT、SERIES_TOO_LONG（清洗后的网格长于模型上下文）、RAW_INPUT_INVALID 等；排队超时返回 503 SERVICE_UNAVAILABLE（带 Retry-After，稍后重试） |
| 推理 | 把清洗后的序列交给模型，生成点预测与区间。 | MODEL_BUSY、GATEWAY_TIMEOUT、SERVICE_UNAVAILABLE |
| 结算 | 按实际计费点数结算预占，返回响应。 | — |
任何阶段失败，都会释放已预占的点数，错误响应不计费。
2. 推荐的接入步骤
- 在 SequenxAI 平台创建
sqx_live_…密钥，保存在服务端环境变量中。 - 先用
/v1/clean预演：确认频率、时区与清洗决定符合预期。这一步免费。 - 调用
/v1/forecast，记录响应中的request_id、effective_policy.id与usage。 - 按
error.code处理失败：422 修改请求，429 与 503/504 按Retry-After重试，见错误码与排障。