开发者文档：/v1/forecast 与 /v1/clean 已开放，API 密钥在 SequenxAI 平台自助创建。

在预测工作台试用 ↗获取 API 密钥 ↗
EN

错误码与排障

本页列出 POST /v1/forecast 与 POST /v1/clean 实际会返回的全部错误码。任何错误响应都不计费。

速查表

HTTP错误码category怎么处理
400MALFORMED_JSON、VALIDATION_ERROR（仅请求头）invalid_request发送合法 JSON 与符合规则的 Idempotency-Key。
401INVALID_API_KEYauth核对 API 密钥。
403INSUFFICIENT_SCOPE、ACCOUNT_SUSPENDED、ORG_PENDING_DELETIONauth换用具备权限范围的密钥；联系支持，或取消工作区删除。
409IDEMPOTENCY_IN_PROGRESSconflict稍后用同一个键重试。
422VALIDATION_ERROR（请求体）、IDEMPOTENCY_KEY_REUSED、CLEANING_OPTION_UNSUPPORTEDinvalid_request按 details 指出的字段或选项修正。
422SERIES_DISCONTINUOUS、TIMESTAMP_IRREGULAR、FREQ_INFERENCE_FAILED、FREQ_AMBIGUOUS、FREQ_UNSUPPORTED、SERIES_EMPTY、SERIES_TOO_SHORT、AMBIGUOUS_DATE_FORMAT、RAW_INPUT_INVALID、FUTURE_COVARIATES_INVALID、COVARIATE_COLUMN_MISMATCHdata_invalid修正数据，或交给清洗修复；details 说明具体问题。
422POINTS_EXCEEDED、SERIES_TOO_LONG、HORIZON_EXCEEDS_MODELlimit_exceeded缩小请求：减少行数、缩短历史或减小 h。
422MODEL_NOT_AVAILABLE、MODEL_OPTION_UNSUPPORTED、QUANTILE_UNSUPPORTEDmodel_unavailable使用 hora-1.0 及其支持的选项与分位数。
429RATE_LIMIT_EXCEEDEDrate_limited等待 Retry-After 秒；每日额度在下一个 UTC 零点恢复。
500 / 503 / 504INTERNAL_SERVER_ERROR、SERVICE_UNAVAILABLE、MODEL_BUSY、GATEWAY_TIMEOUTserver指数退避后重试，有 Retry-After 时按它等待。

retryable 只在 409、429、500、503、504 时为 true，其余均为 false。OpenAPI 契约在 ErrorDetail → x-error-codes 中列出每个错误码的状态码、category 与 retryable。

1. 错误信封

所有错误都以 JSON 返回，顶层只有一个 error 对象：

error-response.json
{
  "error": {
    "code": "HORIZON_EXCEEDS_MODEL",
    "category": "limit_exceeded",
    "retryable": false,
    "message": "h=1500 exceeds the maximum horizon 1024 of model 'hora-1.0'",
    "request_id": "req_0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a",
    "details": {"model": "hora-1.0", "h": 1500, "max_horizon": 1024}
  }
}
字段说明
code机器可读的错误码，按它分支处理，不要解析 message。
categorycode 的大类：invalid_request、data_invalid、limit_exceeded、model_unavailable、auth、conflict、rate_limited 或 server（见上方速查表）。今后可能新增取值；需要精确原因时按 code 处理。
retryable原样重发同一请求可能成功时为 true（409 IDEMPOTENCY_IN_PROGRESS、429、500、503、504）；请求本身需要修改时为 false。每日额度触发的 429 也是 true，但要到下一个 UTC 零点才会恢复。
message面向开发者的英文说明，措辞可能调整。
request_id服务端请求 ID，与响应头 X-Request-Id 相同；联系支持时请提供。
details可选的补充信息，内容随错误码不同，见下表。

未开放的路径（例如 /v1/anomaly-detection、/v1/batch/forecast）返回不带此信封的 404。

2. 请求与认证

错误码HTTP何时出现怎么处理
MALFORMED_JSON400请求体不是合法 JSON。用 JSON 库序列化请求体，不要手工拼接字符串。
VALIDATION_ERROR400仅限请求头（请求体问题返回 422，见下）：Idempotency-Key 不是 1–255 个可打印 ASCII 字符，或与同时传入的已弃用 X-Idempotency-Key 取值不同（details.field 指明对应请求头）。换用符合规则的键，例如 UUID，并只传 Idempotency-Key。
IDEMPOTENCY_KEY_REUSED42224 小时内同一个 Idempotency-Key 配了不同的请求体。不会执行，也不计费。新的请求换一个新键；重试则发送与首次完全相同的请求体。
IDEMPOTENCY_IN_PROGRESS409同一个 Idempotency-Key 的第一次请求仍在处理。稍后用同一个键重试，即可拿到保存的结果。见认证与请求头。
INVALID_API_KEY401缺少 Authorization、格式不是 Bearer <key>、密钥不存在、已删除或已被吊销，或使用了 sqx_test_* 测试密钥。在 SequenxAI 平台核对密钥是否仍在列表中；真实 API 只接受 sqx_live_*。
INSUFFICIENT_SCOPE403密钥缺少 forecast:write 权限范围。换用在 SequenxAI 平台新建的密钥（默认带该范围）。
ACCOUNT_SUSPENDED（beta）403该密钥所属账号或工作区已被 SequenxAI 停用；密钥本身仍有效，恢复后可继续使用。不计费。联系 SequenxAI 支持。
ORG_PENDING_DELETION（beta）403该密钥所属工作区处于删除冷静期，其 API 密钥暂停使用。不计费。在 SequenxAI 平台取消该工作区的删除；取消后密钥立即恢复可用。
VALIDATION_ERROR422仅限请求体（请求头问题返回 400，见上）：字段类型或取值不符合契约、出现契约外的顶层字段、请求体不是 JSON 对象、协变量列超过 8 列、raw 预设缺少 freq、model_options 含未知的键、options.timezone 不是有效的 IANA 名称、ds 无法解析为时间戳。看 details.field，或 details.errors[]（每项含 field 与 message，最多 10 条）。
FUTURE_COVARIATES_INVALID422future_covariates 行里含 y，或缺少字符串类型的 unique_id / ds。future_covariates 只放协变量列；见协变量支持现状。
COVARIATE_COLUMN_MISMATCH422future_covariates 的列在 series 行上不存在，details.future_only 列出这些列。在 series 中补上该列的历史值，或从 future_covariates 中去掉。
POINTS_EXCEEDED422请求行数超过单次上限（/v1/forecast 200,000，series 与 future_covariates 合计；/v1/clean 200,000），或按规则网格展开后的点数过多。上限按清洗主机内存设定，原样重试不会成功。拆分请求；details 含 points 与 cap。

3. 清洗策略与模型

错误码HTTP何时出现怎么处理
CLEANING_OPTION_UNSUPPORTED422未知的 options.cleaning.preset 或 options.cleaning.version；raw 与 accept / decline 或清洗参数同时使用；在已弃用的 2026-10 版本下使用清洗参数（impute_method … long_gap），或使用该版本不提供的 nonnegative 取值；在 /v1/clean 上使用 raw（包括来自密钥或组织默认的 raw）。预设只取 default、strict、raw；details.field 指出问题字段，details.allowed 列出可选值。清洗参数被拒时，details.requires_version 给出所需版本（或由 details.options 与 details.supported 列出可用取值）：不传 version 即使用默认的 2026-12。见清洗策略版本参考。
MODEL_NOT_AVAILABLE422/v1/forecast 或 /v1/clean 的 model 不是 hora-1.0 或其别名 hora。在额度预占之前拒绝，不计费。传 hora-1.0 或省略 model；details 含 model（你发送的 id）与 available。见模型与能力上限。
MODEL_OPTION_UNSUPPORTED422model_options 中有所选模型不支持的键。hora-1.0 同时支持 nonnegative 与 flip_average，目前不会出现。不计费。去掉 details.unsupported 中的键；details 含 model、unsupported、supported。
HORIZON_EXCEEDS_MODEL422h 超过模型的最大步长（hora-1.0 为 1,024）。减小 h，或把长步长拆成多次请求；details 含 model、h、max_horizon。见模型与能力上限。
QUANTILE_UNSUPPORTED422quantile_policy: strict 下，level 或 point_quantile 需要的分位数不在所选模型的原生分位点中。不计费。改用原生可得的水平 / 分位数或去掉 strict；details 含 model、level、unsupported、supported，point_quantile 不是原生值时还有 point_quantile。见预测区间。
RAW_INPUT_INVALID422raw 预设下数据不是规则、有限的序列。按 details.violations[] 修正，或改用 default 预设。见 raw 预设。
SERIES_TOO_LONG422某个实体长于所选模型的最大上下文。按 unique_id 统计模型实际会收到的点数：raw 预设看行数，清洗前看不重复的时间戳数，清洗后看规则网格的长度（details.measured 为 rows / timestamps / model_input）。若实体中有一段长到清洗会只保留最新一段的缺口（见 options.gap_split_min_steps），清洗前不拦，由清洗后的检查决定。服务端不会替你截断历史。不计费。对 details.series 中的实体只发送最近 details.max_context 个点（最多列出 10 个，按长度降序；details.series_count 是总数）。见模型与能力上限。
SERIES_TOO_SHORT422清洗后某个实体的点数少于模型的最小上下文。提供更长的历史（hora-1.0 每个实体至少 16 个点）。

4. 数据被清洗阶段拒绝

以下错误都在 error.details.cleaning_report 中附带完整的清洗报告；blocking[] 指出具体实体与原因，decisions[] 中 proposed 的决定可以按 id 采纳。先用 /v1/clean 预演最省事。

错误码HTTP何时出现怎么处理
SERIES_DISCONTINUOUS422在默认策略版本 2026-13 下，存在 0.75 个季节周期及以上的近期缺口，或缺失占比达到 35%（blocking 为 health_critical，reason 为 gap_near_origin_too_long 或 missing_share_too_high）；在已弃用的版本下，缺口与空值合计占比达到 10%；或需要填补缺失，但 clean_series 为 false 或预设为 strict（cleaning_required，reason: series_discontinuous）；或从策略版本 2026-12 起，序列末尾连续空值的步数超过可保留的上限（3 步），或你撤回了 gap.masked_tail（trailing_gap_too_long，带 count 与 max_steps）。补齐数据；或开启 clean_series、改用 default；strict 下可按 id 采纳 gap.impute 等决定。若 blocking 带 caused_by，说明缺失是缺失值代码判定造成的，按其中的 decline / accept 提示调整。遇到 trailing_gap_too_long 时，发送最新的观测值，或去掉末尾的空行。
TIMESTAMP_IRREGULAR422存在重复、乱序或偏离网格的时间戳需要修复，但 clean_series 为 false，或 strict 预设不允许相应的删除（reason: timestamp_irregular）。在客户端先对齐时间戳，或开启 clean_series；strict 下可按 id 采纳。
FREQ_INFERENCE_FAILED422无法推断稳定的采样频率，或偏离网格的时间戳超过 10%。显式传入 freq。
FREQ_AMBIGUOUS422省略 freq 时，多个实体推断出不同频率，或频率存在多个候选。显式传入 freq，或把不同频率的实体分开请求。
FREQ_UNSUPPORTED422freq 字符串无法识别。按频率字符串的写法传入。
SERIES_EMPTY422某个实体没有任何数值型 y，或清洗后没有可用序列。移除该实体或补充观测值。
AMBIGUOUS_DATE_FORMAT422D/M/YYYY 类时间戳无法从数据判断日月顺序。传 options.ds_format（dmy 或 mdy），或改用 ISO 8601。

5. 限流与服务端

错误码HTTP何时出现怎么处理
RATE_LIMIT_EXCEEDED429每分钟请求数超限（forecast-rpm / clean-rpm），或每日点数额度不足（forecast-daily-points）。等待 Retry-After 秒后重试；每日额度在下一个 UTC 零点恢复。响应头与 details 见计量、额度与限流。
SERVICE_UNAVAILABLE503清洗或推理阶段暂时不可用、所选模型暂不可用、共享清洗容量在整个排队等待期间一直已满，或 SequenxAI 临时暂停了该接口（后两种情况带 Retry-After）。稍后重试，建议指数退避；有 Retry-After 时按它等待。
MODEL_BUSY503模型繁忙。等待 Retry-After 秒后重试。
GATEWAY_TIMEOUT504推理没有在请求时间预算内完成。稍后重试；可减少实体数或 h。
INTERNAL_SERVER_ERROR500未预期的内部错误。稍后重试；持续出现时带上 request_id 联系支持。

6. 契约中列出但当前不会返回的错误码

OpenAPI 的示例里还有以下错误码，对应的功能尚未在公开 API 上实现，目前不会出现：

错误码原因
IP_NOT_ALLOWED（403）密钥暂无 IP 白名单。
DUPLICATE_TIMESTAMPS（422）只在「重复时间戳即拒绝」的策略下出现，公开 API 当前不开放该选项；重复时间戳按保留最后一条处理。
JOB_NOT_FOUND（404）批处理端点尚未开放（契约标为 x-availability: planned），目前请求返回不带信封的 404，不会出现此错误码。

7. 重试建议

  • 可以重试（retryable 为 true）：429（等待 Retry-After）、500、503、504，以及 409 IDEMPOTENCY_IN_PROGRESS（稍后用同一个键）。这些响应都不计费。
  • 不要原样重试（retryable 为 false）：400、401、403、422。请求本身需要修改。
  • 每日额度 429（X-RateLimit-Limit-Type: daily）要到下一个 UTC 零点才会恢复，不适合在进程内等待。
retry.py
import time

import requests


def retryable(resp):
    """error.retryable: whether the same request may succeed when sent again."""
    try:
        return resp.json()["error"]["retryable"] is True
    except (ValueError, KeyError, TypeError):
        return False


def post_with_retry(url, payload, headers, attempts=4):
    for attempt in range(attempts):
        resp = requests.post(url, json=payload, headers=headers, timeout=180)
        if resp.ok or not retryable(resp) or attempt == attempts - 1:
            return resp
        # The daily point quota only frees up at the next UTC midnight: surface it, do not sleep.
        if resp.headers.get("X-RateLimit-Limit-Type") == "daily":
            return resp
        # 429 and MODEL_BUSY carry Retry-After; the other retryable errors usually do not.
        time.sleep(int(resp.headers.get("Retry-After", 2 ** attempt)))
    return resp