错误码与处理方法
API 返回的错误响应包含 code 和 message 字段。客户端应根据 code 区分错误原因,并向用户展示 message。
错误响应格式
{
"code": "invalid_aspect_ratio",
"message": "不支持的画幅比例"
}创建任务时的完整错误响应:
{
"error": {
"code": "invalid_aspect_ratio",
"message": "不支持的画幅比例"
}
}参数与素材错误
其他可能的错误
除上述参数错误外,API 也可能返回以下类型的错误:
任务创建失败 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 };
};常见问题排查
检查你的 aspect_ratio 值是否真的被模型支持。查看模型能力表或尝试删除该字段(某些模型有默认值)。
Base64 仅对视频请求被禁用。图片可以使用 Base64,但建议用 HTTPS URL 以提高效率。
检查 URL 是否需要登录、是否过期、是否返回 HTML 而非媒体文件,或者服务端是否能访问该地址。
创建失败时没有 task_id;任务失败时有 task_id 和 status: failed。