错误码说明

本文档列出了瀑布消息开放API可能返回的所有错误码及其说明。

🔍 错误响应格式

所有API错误都遵循统一的响应格式：

{
  "code": 错误码,
  "message": "错误描述信息"
}

成功响应

{
  "code": 1,
  "message": "操作成功！",
  "data": {}
}

📋 错误码列表

🔧 系统错误 (10000-10099)

错误码	错误信息	说明	解决方案
10000	请求未知异常,请联系平台反馈	系统内部错误	联系技术支持

🔐 认证相关错误 (10011-10019)

错误码	错误信息	说明	解决方案
10003	应用密钥不能为空，字段：accessSecret	未提供accessSecret参数	检查请求参数，添加accessSecret
10011	应用不存在	提供的accessSecret无效	检查accessSecret是否正确
10012	应用待审核	应用还未通过审核	等待管理员审核通过
10013	应用状态异常	应用被禁用或状态错误	联系管理员检查应用状态

📝 参数验证错误 (10001-10010, 10017-10019)

错误码	错误信息	说明	解决方案
10001	发送范围参数不正确，字段：pushRange，1：全部用户，2：指定用户	pushRange参数值错误	设置pushRange为1或2
10002	发送时间类型不正确，字段：pushTimeType，1：立即发送，2：定时发送	pushTimeType参数值错误	设置pushTimeType为1或2
10008	发送者ID不能为空，字段：pushIds	pushRange=2时未提供pushIds	指定用户发送时必须提供pushIds
10009	定时发送时间不能为空，字段：pushTime	pushTimeType=2时未提供pushTime	定时发送时必须提供pushTime
10010	定时发送时间不能早于当前时间	定时时间设置错误	设置未来的时间点
10017	模板ID不能为空，字段：templateId	未提供templateId参数	检查请求参数，添加templateId
10019	参数异常:%s	通用参数错误	根据具体错误信息调整参数

📄 模板相关错误 (10005, 10014-10016)

错误码	错误信息	说明	解决方案
10005	模板不存在	提供的templateId无效	检查templateId是否正确
10014	模板待审核	模板还未通过审核	等待管理员审核通过
10015	模板状态异常	模板被禁用或状态错误	联系管理员检查模板状态
10016	模板ID参数异常	模板权限验证失败	检查是否有权限使用该模板

📋 内容相关错误 (10004, 10006-10007, 10018)

错误码	错误信息	说明	解决方案
10004	发送内容不能为空，字段：affiliatedJson	未提供affiliatedJson参数	检查请求参数，添加affiliatedJson
10006	发送内容不能为空，字段：affiliatedJson	affiliatedJson为空数组	提供有效的模板变量内容
10007	发送内容参数序列化异常，字段：affiliatedJson	JSON格式错误	检查affiliatedJson格式是否正确
10018	affiliatedJson字段内容缺失：[字段列表]	模板变量不完整	补充缺失的模板变量

🔧 错误处理最佳实践

1. 基础错误处理

async function handleApiResponse(response) {
  const result = await response.json();
  
  if (result.code === 1) {
    // 成功处理
    return result.data;
  } else {
    // 错误处理
    console.error(`API错误 [${result.code}]: ${result.message}`);
    throw new Error(result.message);
  }
}

2. 详细错误处理

async function sendMessageWithErrorHandling(sendData) {
  try {
    const response = await fetch('https://waterfallapi.zhaoyizhe.com/waterfall/wapi/send', {
      method: 'POST',
      headers: {'Content-Type': 'application/json'},
      body: JSON.stringify(sendData)
    });
    
    const result = await response.json();
    
    switch(result.code) {
      case 1:
        console.log('消息发送成功');
        return true;
        
      case 10003:
      case 10011:
        console.error('认证失败，请检查accessSecret');
        // 处理认证问题
        break;
        
      case 10005:
        console.error('模板不存在，请检查templateId');
        // 处理模板问题
        break;
        
      case 10007:
        console.error('JSON格式错误，请检查affiliatedJson格式');
        // 处理JSON格式问题
        break;
        
      case 10010:
        console.error('定时时间设置错误，不能早于当前时间');
        // 处理时间设置问题
        break;
        
      default:
        console.error(`未处理的错误: [${result.code}] ${result.message}`);
    }
    
    return false;
    
  } catch (error) {
    console.error('网络请求失败:', error);
    return false;
  }
}

3. Python 错误处理

import requests
import json

def send_message_with_error_handling(send_data):
    """发送消息并处理错误"""
    url = "https://waterfallapi.zhaoyizhe.com/waterfall/wapi/send"
    
    try:
        response = requests.post(url, json=send_data)
        result = response.json()
        
        if result['code'] == 1:
            print('消息发送成功')
            return True
        else:
            error_code = result['code']
            error_message = result['message']
            
            # 根据错误码进行不同处理
            if error_code in [10003, 10011]:
                print(f'认证失败: {error_message}')
            elif error_code == 10005:
                print(f'模板错误: {error_message}')
            elif error_code == 10007:
                print(f'JSON格式错误: {error_message}')
            elif error_code == 10018:
                print(f'模板变量缺失: {error_message}')
            else:
                print(f'API错误 [{error_code}]: {error_message}')
            
            return False
            
    except requests.RequestException as e:
        print(f'网络请求失败: {e}')
        return False
    except json.JSONDecodeError as e:
        print(f'响应解析失败: {e}')
        return False

📊 常见错误场景及解决方案

场景1: 模板变量不匹配

错误: 10018 - affiliatedJson字段内容缺失：[${title}, ${content}]

原因: 提供的模板变量与模板定义不匹配

解决方案:

1. 先调用获取模板列表接口，查看模板的 affiliatedJson 定义
2. 确保提供的变量包含所有必需的 key
3. 检查变量名拼写是否正确

// 错误示例
const wrongData = [
  {"key": "${title}", "value": "标题"}
  // 缺少了 ${content} 变量
];

// 正确示例  
const correctData = [
  {"key": "${title}", "value": "标题"},
  {"key": "${content}", "value": "内容"}
];

场景2: 定时发送时间设置错误

错误: 10010 - 定时发送时间不能早于当前时间

解决方案:

// 错误示例
const pastTime = "2024-01-01 12:00:00"; // 过去的时间

// 正确示例
const futureTime = new Date();
futureTime.setHours(futureTime.getHours() + 1); // 1小时后
const pushTime = futureTime.toISOString().slice(0, 19).replace('T', ' ');

场景3: JSON格式错误

错误: 10007 - 发送内容参数序列化异常，字段：affiliatedJson

解决方案:

// 错误示例
const wrongJson = '[{"key": "${title}", "value": "标题",}]'; // 多余的逗号

// 正确示例
const correctJson = JSON.stringify([
  {"key": "${title}", "value": "标题"}
]);

📞 技术支持

如果遇到文档中未涵盖的错误码或需要技术支持：

• 📧 邮箱: zhangxiao@zhaoyizhe.com
• 💬 公众号: 瀑布消息
• 🔍 请提供完整的错误码和错误信息

---

相关文档： 发送消息 | 获取模板列表 | 获取用户列表