How to Trigger a Step Function via HTTP API? Receiving 500 Internal Server Error

Question

Hi ,

I’m trying to trigger a Step Function by sending a POST request to an HTTP API endpoint. However, I keep receiving a 500 Internal Server Error. Below is the code I’m using:

```
const requestData = {
    input: {
        Brand: 'TEST'
    }
};

const options = {
    method: 'POST',
    headers: { 
        'accept': 'application/json', 
        'content-type': 'application/json'
    },
    body: JSON.stringify(requestData)
};

fetch('https://.../model', options)
    .then(response => {
        console.log('Status:', response.status);
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return response.json();
    })
    .then(data => console.log('Success:', data))
    .catch(err => {
        console.error('Error details:', err);
        console.log('Request data:', requestData);
    });
```

I’d appreciate your help with the following questions:

Is this the correct way to trigger a Step Function via an HTTP API using fetch?

If the API Gateway is integrated directly with a Step Function (AWS service integration), what is the expected request body format?

What are the recommended steps to debug a 500 Internal Server Error in this setup, especially if no error message is returned in the frontend?

Additional context:

The Step Function runs successfully when triggered manually via the AWS Console.

The API Gateway is set up as an HTTP API endpoint.

I’m not using any authentication (e.g., Cognito or IAM) in this fetch request at the moment.

Thank you in advance for your assistance!

Best regards,

re:Post Agent · Answer

When triggering a Step Function via an HTTP API, there are several aspects to consider to resolve your 500 Internal Server Error.

First, regarding your request format, when using API Gateway to invoke a Step Function, all Step Functions API actions use the HTTP `POST` method, so your approach of using a POST request is correct. However, the body structure might need adjustment.

For the request body format when API Gateway is integrated directly with a Step Function, you need to ensure it matches what the `StartExecution` API action expects. The body should typically include:

1. The state machine ARN (if not configured in the mapping template)
2. The input for the state machine execution

Your current request structure has an additional nesting level with the `input` property that might be causing issues. Try modifying your request body to directly include your data:

```
const requestData = {
Brand: 'TEST'
};
```

If you've configured a mapping template in API Gateway, make sure your request body aligns with that template's expectations.

To debug a 500 Internal Server Error in this setup:

1. Check the CloudWatch Logs for your API Gateway to see the detailed error messages
2. Verify the IAM permissions - ensure that API Gateway has the necessary permissions to invoke the Step Function (it needs a role with `AWSStepFunctionsFullAccess` or appropriate permissions)
3. Confirm that the integration is properly set up in API Gateway to call the `StartExecution` API action
4. Test the API directly using tools like Postman or AWS CLI to isolate if the issue is with your frontend code or the API configuration
5. Verify that the state machine ARN is correctly specified in your API Gateway configuration

Since your Step Function runs successfully when triggered manually, the issue is likely related to how API Gateway is invoking the Step Function or how your request is structured. Double-check the integration configuration in API Gateway and ensure it's properly set up to call the `StartExecution` action with the correct parameters.  
**Sources**  
[Creating a Step Functions API using API Gateway - AWS Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/tutorial-api-gateway.html)  
[Starting state machine executions in Step Functions - AWS Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/statemachine-starting.html)

How to Trigger a Step Function via HTTP API? Receiving 500 Internal Server Error

Add your answer

Relevant content