MiniMax H3 429 报错怎么解决？限流原因与重试设置

MiniMax H3 报 429，表示这次请求触发了限流，不是模型不可用。官方错误码表里它对应 1002（rate limit），限额是视频生成 V2 接口给 MiniMax-H3 的 300 RPM、最多 30 个进行中任务，超了就报这个。

先对号入座：三种最常见的触发场景

1. 批量提交不等待。循环里一口气创建几十个视频任务，请求数瞬间冲破 300 RPM。
2. 忽略异步语义。H3 的 /v2/video_generation 是异步接口，创建成功只返回一个 task_id，正确做法是轮询查询接口拿结果。有人在没拿到视频时反复重新创建，并发任务数很快堆到 30 的上限。
3. 多人或多进程共用一个 API Key。本地并发乘上机器数量，实际速率早就超标。

429 背后其实是四种不同原因

先对着这张表分清你属于哪一种：

1008 和 2056 无论重试多少次都不会好，只能充值或等额度释放。用同一套重试逻辑处理全部 429，大概率是在白等。

逐条解法

1. 把并发压到限额以内

官方限流表在 Video Generation V2 这一行给 MiniMax-H3 的数值是 300 RPM、Max inflight tasks 30。本地用并发池控制，比如信号量设 20 留出余量。批量任务要避开整点定时一次性打满，拆成分片、片间留间隔，这同时能规避 2045 那类增速限制。

2. 用带抖动的指数退避重试

import random
import time

import requests

def create_task(payload, api_key, max_retry=5):
    for attempt in range(max_retry):
        resp = requests.post(
            "https://api.minimax.io/v2/video_generation",
            headers={"Authorization": f"Bearer {api_key}"},
            json=payload,
            timeout=30,
        )
        if resp.status_code == 429:
            wait = min(2 ** attempt, 30) + random.uniform(0, 1)
            time.sleep(wait)
            continue
        resp.raise_for_status()
        return resp.json()["task_id"]
    raise RuntimeError("连续重试仍被限流，先检查这个 Key 的并发占用")

加随机抖动不能省，否则多个进程会在同一秒一起重试，继续撞限流。

3. 拿到 task_id 之后只轮询

重复创建是把自己推进并发上限最快的方式，还会白白浪费额度。正确流程是创建一次，之后只调查询接口，等状态变成 succeeded。

4. 额度不够就提额

现有 300 RPM 不够用，官方渠道是发邮件到 api@minimax.io 申请提升。

官方口径（附原文）

• 错误码表：1002 对应 rate limit，官方建议是 Please retry your requests later。
• 限流文档：Video Generation V2 接口下 MiniMax-H3 为 300 RPM、Max inflight tasks 30。限额按你的账号计算，与模型和接口有关，所以多开 Key 并不会提高上限。
• 429 响应示例，来自官方 OpenAPI 文档：

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "rate limit, please retry later (1002)",
    "http_code": "429"
  },
  "request_id": "021785229015510a2c883cf675b9804d"
}

原文地址：错误码表、限流规则、视频生成 V2 接口。

预防：三条长期有效的做法

1. 本地队列加并发上限，把提交和消费速度解耦，程序不会自己把接口打满。
2. 监控 429 占比，超过阈值自动降速，而不是硬重试。
3. 生成结果存进自己的存储，同一素材不要重复提交。

H3 的模型能力与本地部署方式，站内 MiniMax H3 是什么 那篇已经写过；如果你用快速档位，可对照 MiniMax H3 Max 的 API 参数。另外 Ox Alpha 报错排查 也是同类 429 问题，思路可以互相参考。