Agora云录制启动失败：500错误（Code 2）请求体校验失败

问题背景 #

调用Agora Cloud Recording混合模式下的/start API启动录制时，返回500错误，错误码为2，提示「post method api body check failed!」。已完成以下操作但问题仍未解决：

• 成功获取resourceID
• 使用PUBLISHER角色生成并验证了token
• 核对AWS S3存储信息
• 尝试uid的字符串与整数格式

技术环境：Node.js（Axios发起请求），Agora Cloud Recording RESTful API v1

当前请求体 #

{  
  "cname": "myChannelName",
  "uid": "0",
  "clientRequest": {
    "token": "007eJxTYFi+...",
    "recordingConfig": {
      "maxIdleTime": 30,
      "streamTypes": 2,
      "channelType": 1,
      "videoStreamType": 0,
      "transcodingConfig": {
        "height": 640,
        "width": 360,
        "bitrate": 500,
        "fps": 15,
        "mixedVideoLayout": 1
      }
    },
    "recordingFileConfig": {
      "avFileType": ["hls", "mp4"]
    },
    "storageConfig": {
      "vendor": 1,
      "region": 0,
      "bucket": "my-agora-bucket",
      "accessKey": "my-access-key",
      "secretKey": "my-secret-key"
    }
  }
}

AWS S3 Bucket IAM策略 #

{    
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation",
                "s3:ListBucketMultipartUploads"
            ],
            "Resource": [
                "arn:aws:s3:::agora-recordings-bucket"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:DeleteObject",
                "s3:AbortMultipartUpload",
                "s3:ListMultipartUploadParts"
            ],
            "Resource": [
                "arn:aws:s3:::agora-recordings-bucket/*"
            ]
        }
    ]
}

问题解答 #

1. 请求体校验失败的可能原因 #

• 字段值与API规范不匹配：包括字段类型错误、取值超出允许范围、内容不一致（如存储桶名称与IAM策略不匹配）
• 缺失混合模式必填的嵌套配置项
• 请求头Content-Type未设置为application/json，导致API无法正确解析请求体
• Token与请求体中的cname/uid不匹配
• resourceID过期或与目标频道不绑定

2. 请求体的格式/字段问题排查 #

从提供的信息来看，存在一个明显的不匹配问题：

• 存储桶名称不一致：请求体中storageConfig.bucket为my-agora-bucket，但IAM策略中授权的存储桶是agora-recordings-bucket，这会直接触发存储配置的校验失败。

其他需要核对的点：

• transcodingConfig的参数：确认width/height/bitrate/fps是否符合Agora的取值范围（比如分辨率需为偶数，码率与分辨率匹配）
• token：确保是针对当前cname和uid生成的有效PUBLISHER角色token，且未过期
• 请求体序列化：Axios发起请求时，需确保直接传入JSON对象（Axios会自动处理序列化），避免手动序列化导致的格式错误

3. Agora API触发Code 2错误的常见操作失误 #

• 嵌套字段层级错误：比如将recordingConfig放在clientRequest外部
• 混合模式下遗漏transcodingConfig配置（该字段为混合模式必填）
• 存储配置字段错误：包括vendor枚举值错误、region与实际存储桶区域不匹配、accessKey/secretKey格式错误
• uid格式不符合要求：API要求uid为字符串类型（即使是0）
• 请求体包含API未定义的多余字段，导致校验不通过

内容的提问来源于stack exchange，提问作者Aymeric Pellan