跳转到正文MaoMaoToken
控制台

错误码与处理方法

API 返回的错误响应包含 code 和 message 字段。客户端应根据 code 区分错误原因,并向用户展示 message。

错误响应格式

{
  "code": "invalid_aspect_ratio",
  "message": "不支持的画幅比例"
}

创建任务时的完整错误响应:

{
  "error": {
    "code": "invalid_aspect_ratio",
    "message": "不支持的画幅比例"
  }
}

参数与素材错误

code含义处理方式
invalid_requestJSON 格式、必填字段或字段类型错误修正请求格式后重试
invalid_seconds时长不是整数或不在模型范围内查看模型能力表,修改 seconds
invalid_resolution清晰度不被模型支持更换为支持的清晰度或更换模型
invalid_aspect_ratio画幅不被模型支持使用模型允许的 aspect_ratio 值
prompt_too_long提示词超过字节限制缩短提示词内容
invalid_references素材结构、类型或 URL 不符合要求检查并修正 references 数组
too_many_reference_images图片素材过多减少图片参考数量
too_many_reference_videos视频素材过多减少视频参考数量
too_many_reference_audios音频素材过多减少音频参考数量
too_many_reference_materials所有素材合计过多减少素材总数
too_many_video_audio_references视频与音频组合超过限制调整组合方式或更换模型
video_base64_not_allowed视频参考包含 Base64 素材改为公网 HTTPS URL
invalid_reference_url素材 URL 不是可访问的公网地址使用无需登录的 HTTPS URL

其他可能的错误

除上述参数错误外,API 也可能返回以下类型的错误:

错误类型示例 code原因
认证错误unauthorized、invalid_api_keyAPI 密钥无效或缺失
额度错误insufficient_quota、insufficient_balance账户余额不足或额度用尽
限流错误rate_limit_exceeded请求频率超过限制
上游错误upstream_error、model_error模型服务异常
服务错误internal_server_error平台服务异常

任务创建失败 vs 任务执行失败

创建失败

  • 返回 HTTP 4xx 状态码
  • 响应中 无 task_id 字段
  • 这些是校验失败,不会产生费用
  • 解决后可以重新提交

执行失败

  • 返回 HTTP 200,但 status: failed
  • 响应中 有 task_id 字段
  • 任务已创建,产生相应费用
  • 应查看 error 字段了解失败原因

错误处理最佳实践

1. 创建请求超时

// 不要立即重试
const response = await fetch('https://api.maomaotoken.com/v1/videos', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${apiKey}` },
  body: JSON.stringify(params),
  timeout: 30000
}).catch(err => {
  // 不要直接重新创建
  console.log('创建超时,应先检查是否已创建');
  // 改为查询之前的 task_id(如果有的话)
  return queryTask(previousTaskId);
});

2. 查询超时

// 查询超时可以安全重试
const query = async (taskId, maxRetries = 3) => {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(
        `https://api.maomaotoken.com/v1/videos/${taskId}`,
        { timeout: 10000 }
      );
      return response.json();
    } catch (err) {
      if (i < maxRetries - 1) {
        await sleep(2 ** i * 1000); // 指数退避
      }
    }
  }
};

3. 错误分类处理

const handleVideoError = (error) => {
  const { code, message } = error;

  // 客户端错误(修正请求后重试)
  if (code.startsWith('invalid_') || code.includes('too_many')) {
    return { retry: true, delay: 0, reason: '参数错误,已修正后重新提交' };
  }

  // 服务端错误(指数退避重试)
  if (code.startsWith('upstream_') || code === 'internal_server_error') {
    return { retry: true, delay: 2 ** retryCount * 1000, reason: '服务异常,稍后重试' };
  }

  // 配额错误(需要充值)
  if (code.includes('quota') || code.includes('balance')) {
    return { retry: false, delay: 0, reason: '额度不足,请充值' };
  }

  // 默认不重试
  return { retry: false, delay: 0, reason: message };
};

常见问题排查

本页内容

On this page