Facebook/Workplace Graph API上传图片至相册报500错误咨询

最高优先级排查：近期API权限变更 #

2024年5月中下旬Meta对Workplace集成权限做了无提前通知的静默拆分：原write_group权限不再覆盖群组相册的图片上传操作，该类内容发布场景现在需要单独的groups_content_manage权限。你当前持有的read_group、write_group、link_unfurling权限集缺少这个新增的必填权限，是这波同类型老应用稳定运行多年突然报错的最主要原因，别先上来反复调本地代码，先查这个。
注意老的长效access_token不会自动继承新权限，哪怕你后台已经给应用加了权限，也要重新走授权流程生成新token才能用。

其余分步排查点 #

• 请求格式问题排查
  你用WebClient.UploadFile的实现有几个常见坑，很容易触发服务端500：
  1. 这个方法默认提交文件的表单字段名是file，但相册上传接口强制要求文件必须放在名为source的表单字段下，字段名不对会直接触发服务端参数解析失败
  2. 别把access_token拼在请求URL里，token里的特殊字符转义问题、URL长度截断都可能导致鉴权异常，建议把token作为POST表单的普通字段提交
  3. 不要手动写Content-Type请求头，让WebClient自动生成带multipart/form-data边界值的头信息，手动写死头信息缺边界值的话，服务端根本解析不了请求体
• 上传文件本身问题排查
  先找一张之前成功上传过的合规测试图走一遍现有流程，排除PDF提取环节出的问题：
  1. 接口目前仅支持小于4MB的JPG、标准RGB色彩模式的PNG文件，WEBP、CMYK模式的图片传上去直接触发转码失败
  2. 分辨率超过2048*2048的带透明通道PNG，近期服务端转码逻辑调整后也会返回500
• 快速定位根因的方法
  发测试请求的时候抓下响应头，把里面的x-fb-trace-id值存下来，如果上面的步骤都排查完还是报错，把这个trace-id、请求时间、请求参数提交给Workplace开发者支持，服务端可以直接通过这个id查到具体的错误栈，不用瞎猜问题。

内容的提问来源于stack exchange，提问作者Gunnar S.