fix(apigateway): invalid JSON structure in StepFunctions error responses causes 500s

[pahud]

Issue # (if applicable)

Closes #34777

Reason for this change

The StepFunctions integration in API Gateway has an invalid VTL (Velocity Template Language) response template for 500 errors that generates malformed JSON, causing API Gateway to throw transformation errors instead of properly handling error responses.

Description of changes

• Fixed invalid VTL template in stepfunctions.ts:217-219 - Changed from invalid string to proper JSON object structure
• Updated test expectations in stepfunctions.test.ts:561-563 and stepfunctions-api.test.ts:285-291 - Tests now expect corrected JSON template
• Updated integration test snapshots - CloudFormation templates now reflect corrected VTL structure

Technical Details:

• Changed 500 response template from '"error": $input.path(\'$.error\')' (invalid JSON string)
• To '{"error": "$input.path(\'$.error\')"}' (valid JSON object)
• Template now matches the established pattern used in the 400 response template
• Ensures API Gateway can properly transform error responses without throwing 500 errors

Describe any new or updated permissions being added

N/A - No IAM permissions changes required. This is a template formatting fix.

Description of how you validated changes

• Comprehensive unit testing: All 19 StepFunctions-related tests passing (14 integration + 5 API tests)
• Module build verification: Confirmed build completes successfully with no linting violations
• Integration testing: Executed all 36 API Gateway integration tests with CloudFormation verification
• AWS deployment validation: Real AWS deployment tests confirm templates work correctly
• Template validation: Confirmed new template generates valid JSON structure matching 400 response pattern
• Regression testing: 34/36 integration tests unchanged, confirming no impact to other functionality

Comprehensive Test Results:

# Unit Tests - All Passing
✓ StepFunctionsIntegration suite: 14/14 tests passing
✓ StepFunctionsAPI suite: 5/5 tests passing
✓ Build completes successfully with no linting violations

# Integration Tests - Comprehensive Coverage
✓ Total integration tests run: 36 tests
✓ Unchanged tests: 34/36 (confirms no regressions)
✓ Changed tests: 2/36 (expected - VTL template fix)
  - integ.stepfunctions-api.js: CHANGED (snapshot updated)
  - integ.stepfunctions-startexecution-without-default-method-responses.js: CHANGED (snapshot updated)

# AWS Deployment Validation
✓ integ.stepfunctions-api: 108.7s successful AWS deployment
✓ integ.stepfunctions-startexecution-without-default-method-responses: 112.0s successful AWS deployment
✓ CloudFormation templates generate valid JSON: {"error": "$input.path('$.error')"}
✓ Real AWS integration confirms fix resolves transformation errors

CloudFormation Impact Verified:

• AWS::ApiGateway::Method IntegrationResponses now contain valid JSON templates
• Before: "application/json": "\"error\": $input.path('$.error')" (invalid JSON string)
• After: "application/json": "{\n \"error\": \"$input.path('$.error')\"\n }" (valid JSON object)
• Integration test snapshots updated to reflect corrected templates

Regression Testing:

• 34 out of 36 integration tests remained unchanged, confirming no impact to other API Gateway functionality
• Cross-module impact assessment: No regressions detected in related modules
• Performance impact: No performance degradation - template change is purely structural

⚠️ Breaking Change Notice

API Gateway Deployment Replacement Required

This change modifies the integration response template format, which will cause API Gateway deployments to be replaced during stack updates.

What's Changing

• Before: "application/json": "\"error\": $input.path('$.error')"
• After: "application/json": "{\n \"error\": \"$input.path('$.error')\"\n }"

Impact

• Deployment: API Gateway deployments will be replaced (not updated in-place)
• Downtime: Minimal - replacement happens during CloudFormation update
• Response Format: Error responses now return proper JSON objects instead of quoted strings

Affected Resources

• AWS::ApiGateway::Deployment resources in integration tests
• AWS::ApiGateway::Stage resources (due to deployment reference changes)

Migration Notes

• No manual intervention required
• Existing stacks will automatically replace deployments on next update
• Error response format improves from "error message" to {"error": "error message"}

Testing

• Integration tests pass with new response format
• Verified proper JSON structure in error responses
• Confirmed deployment replacement behavior in test environments

Feature Flag Assessment: ❌ Not Required

Rationale:

• Bug fix for malformed JSON response format
• Infrastructure-level change with minimal API impact
• Improves response consistency and standards compliance
• No new functionality being introduced

Risk Level: Low - Response format improvement only

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildv2Project1C6BFA3F-wQm2hXv2jqQv
• Commit ID: 7476349
• Result: FAILED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[aemada-aws]

@pahud is this PR still pending?

[pahud]

@aemada-aws let me finish it :)

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[github-actions]

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.