API Gateway网关超时时如何配置面向终端用户的自定义错误提示?
API Gateway 30s超时自定义响应实现方案
首先明确核心逻辑:API Gateway触发30s超时阈值时,会主动切断与前端的请求链路,此时关联的Lambda函数仍在后台执行,根本没有机会返回自定义内容覆盖默认响应,因此所有配置需在API Gateway侧完成,无需修改Lambda业务代码。
具体配置步骤
- 进入对应API的管理控制台,定位到经常触发超时的路由/接口方法
- 配置网关级别的504状态码自定义响应:
- 若使用REST API:在「网关响应」配置列表中找到
DEFAULT_504类型的响应规则,开启自定义配置。可按需调整三个核心项:- 响应状态码:默认保持504即可,也可根据前端适配逻辑调整为前端可正常解析的状态码
- 响应头:补上和正常接口一致的CORS跨域配置(比如
Access-Control-Allow-Origin),避免浏览器拦截响应内容导致自定义提示无法展示 - 响应模板:替换默认的报错内容为用户引导信息,例如
{"msg":"当前请求处理超时,请检查提交的查询条件是否合理,或等待30秒后重试,若多次出现该问题可联系系统管理员排查","canRetry":true}
- 若使用HTTP API:在「路由响应」配置页,为对应路由关联504状态码的响应规则,同样可自定义响应体模板、补充跨域响应头
- 若使用REST API:在「网关响应」配置列表中找到
- 完成配置后,必须重新部署API到对应运行环境:所有API Gateway的配置变更不会自动同步到线上环境,需手动执行部署操作,将修改推送到生产/预发阶段,否则配置完全不生效。
常见踩坑提醒
不要尝试通过Lambda内部的超时捕获逻辑实现自定义提示:因为API Gateway已经在30s时主动断开了和前端的连接,Lambda后续执行完成返回的内容根本无法推送到用户端,这部分改动对超时场景的自定义响应没有任何作用。
一定要核对自定义响应头和正常接口的配置一致性:如果CORS头缺失,浏览器会直接拦截跨域返回的自定义内容,用户看到的依然是网关默认的跨域报错,而非你配置的引导信息。
如果不同接口需要展示不同的超时引导,可针对单条路由单独配置专属的504响应模板,无需做全局统一的提示配置。
内容的提问来源于stack exchange,提问作者Rakesh Goswami
相关产品推荐
相关产品推荐

