如何配置AWS API Gateway未找到Step Function时返回404而非200状态码
问题根因
当前API Gateway直接对接Step Functions的StartExecution做服务集成时,只要网关侧成功把请求转发到Step Functions服务端点,无论Step Functions返回何种业务错误(包括状态机不存在),API Gateway默认会统一返回200 OK,不会自动透传上游服务的错误状态码,这就是异常返回的核心原因。
可落地方案
方案1:配置API Gateway集成响应映射(零额外运维成本)
这个方案不需要新增任何计算资源,仅靠API Gateway原生配置就能实现需求:
- 核心匹配逻辑:Step Functions当检测到指定ARN的状态机不存在时,会在响应体的
error字段返回固定值StateMachineDoesNotExist,我们可以让API Gateway识别这个特征,直接映射成404状态码返回。 - 具体配置步骤:
- 进入对应API方法的集成响应配置页,新增一条响应规则
- 配置响应匹配选择器为
$.error == "StateMachineDoesNotExist" - 将该规则映射的HTTP状态码设置为
404,可自定义响应模板把错误详情透传给调用方 - 收窄默认200响应的匹配范围,避免404规则被默认规则兜底拦截
- 一定要校验绑定给API Gateway的IAM权限,确保其能正常读取Step Functions返回的错误响应体,否则匹配规则会直接失效。
方案2:新增Lambda前置校验层(灵活性更高)
如果需要更精细的错误控制,可以把API Gateway和Step Functions的直连模式改成Lambda代理模式:
- 把API Gateway的后端集成从直连Step Functions,替换为调用一个轻量Lambda函数
- Lambda内的处理流程:
- 从请求参数中解析出传入的
statemachinearn值 - 调用Step Functions的
DescribeStateMachine接口做前置校验 - 如果接口返回状态机不存在的错误,直接返回带404状态码的结构化响应
- 校验通过后,再调用
StartExecution触发目标状态机执行,把执行结果透传给调用方
- 从请求参数中解析出传入的
- 该方案的额外收益是可以顺手实现参数合法性校验、调用日志埋点、自定义权限控制,后续扩展逻辑不需要改动API Gateway的底层配置。
常见配置踩坑提示
- 配置响应映射时要确认规则是加在集成响应层级,不要错加到方法响应的空配置层,否则匹配规则不会生效
- 注意区分错误类型:IAM权限不足导致的调用失败返回的是
AccessDenied错误,不要和真实的状态机不存在的StateMachineDoesNotExist错误混同,避免把权限类问题错误映射为404
内容的提问来源于stack exchange,提问作者harika
相关产品推荐
相关产品推荐

