App Store Connect API 踩坑指南

在公司推行自动化发布流程的时候，我尝试用脚本把 App Store Connect API 跑通，实现从元数据更新到提交审核的全自动化。结果在快速迭代期间被三个极其隐蔽的“硬限制”给坑了，最气人的是，Apple 给出的报错信息完全在误导人。

分享一下这三个坑，建议写自动化部署脚本的同学提前避雷：

一、 JWT Token 的 20 分钟有效期死线

这是最离谱的一个。很多习惯了 Apple 其他 API 的人会把 Token 有效期设长一点，但 ASC API 强制要求 exp - iat <= 1200 秒。

如果你把有效期设为 1201 秒（哪怕只多出 1 秒），所有请求都会报 401 NOT_AUTHORIZED。最坑的地方在于，报错说的是“凭据失效”，你可能会检查半天 Key 或 ID，但实际上是时间戳超限了。

在处理批量上传截图这种长耗时操作时，如果 Token 在中途过期，你会发现前几个请求成功了，后面突然全部 401。

避坑配置（Python 示例）：

import jwt, time

iat = int(time.time())
payload = {
 "iss": ISSUER_ID,
 "iat": iat,
 "exp": iat + 1180, # 必须小于1200秒，留一点时钟偏移余量
 "aud": "appstoreconnect-v1"
}
token = jwt.encode(payload, PRIVATE_KEY, algorithm="ES256",
 headers={"kid": KEY_ID})

二、 只能有一个版本在“飞行中”

ASC 不允许同时存在两个正在处理的版本。如果当前已经有一个版本处于 PREPARE_FOR_SUBMISSION（准备提交）、WAITING_FOR_REVIEW（等待审核）或 IN_REVIEW（审核中），你尝试创建新版本时会直接撞墙：

• 错误响应： 409 STATE_NOT_SUITABLE
• 提示信息： "You cannot create a new version of the App in the current state"

它根本不会告诉你现在是什么状态。解决办法只能是等审核结束，或者通过 API 把当前版本强制设为 developerRejected=true 撤回，才能创建下一个。

三、 审核提交的数量天花板

这个限制最隐蔽，因为它涉及两个不同的计数器，但共用一套报错逻辑：

• 在审上限： WAITING_FOR_REVIEW 和 IN_REVIEW 两个状态加起来最多只能有 2 个。
• 总数上限： 加上 READY_FOR_REVIEW 状态，总数不能超过 5 个。

一旦超限，就会触发 MAX_IN_REVIEW_SUBMISSIONS_PER_PLATFORM_LIMIT_REACHED。如果你在写自动化工作流，记得在提交前先调用接口查询当前版本的状态计数，否则脚本运行到一半崩掉非常影响心情。