Validate Request Body and Parameters in API Gateway (2026)

API Gateway isn’t just a traffic cop; it’s a bouncer that can actually check IDs before letting anyone in.

Imagine you’re building a service that needs to know a user’s age to serve them content. You’ve got an API endpoint /users/{userId}/age that accepts a PUT request. The request body should look like this:

{
  "age": 30
}

And your API Gateway is set up to route this to a backend Lambda function. But what if someone sends a request like this?

{
  "age": "thirty"
}

Or even worse, a completely different structure:

{
  "years_old": 30
}

Your Lambda function, if it’s not robustly written, might crash trying to parse "thirty" as an integer, or it might happily proceed with an empty or incorrect age value if it expects a different key. API Gateway can prevent this entirely.

Here’s how you set up validation for this specific scenario using API Gateway’s request validation feature. We’ll focus on validating the request body.

First, navigate to your API in the API Gateway console. Select the specific resource (/users/{userId}/age) and the method (PUT). In the method execution pane, you’ll find a "Request Validation" section. Click "Edit."

You’ll see options to validate request parameters (query string, path, headers) and the request body. We’re interested in the "Request Body" section.

1. Enable Request Validation: Check the "Enable" box for Request Body Validation.

2. Define the Content Type: In the "Content Type" field, enter application/json. This tells API Gateway to expect JSON data.

3. Link to a JSON Schema: This is where the magic happens. API Gateway uses JSON Schema to define the expected structure and data types of your request body. You need to create a JSON Schema that describes your valid payload. For our example, the schema would look like this:

{
  "type": "object",
  "properties": {
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    }
  },
  "required": [
    "age"
  ],
  "additionalProperties": false
}

Let’s break this schema down:

"type": "object": The root of our payload must be a JSON object.
"properties": Defines the expected keys within the object.
- "age": We expect a key named "age".
- "type": "integer": The value associated with "age" must be an integer.
- "minimum": 0, "maximum": 150: We’re adding some business logic here – ages must be between 0 and 150.
"required": ["age"]: The "age" key is mandatory. If it’s missing, validation fails.
"additionalProperties": false: This is crucial. It means no other properties are allowed in the JSON object besides what’s defined in properties. This prevents unexpected or malicious fields from being sent.

4. Input the Schema: In the API Gateway console, under "Request Body Validation," paste this JSON Schema into the "JSON Schema" text area.

5. Save: Click "Save" or "Update."

Now, when a client sends a PUT request to /users/{userId}/age, API Gateway will intercept it before it even reaches your backend.

Valid Request:
```
{
  "age": 30
}
```
API Gateway will validate this against the schema. It’s an object, has an "age" property, the value is an integer between 0 and 150, and there are no other properties. The request proceeds to your Lambda function.
Invalid Request (wrong type):
```
{
  "age": "thirty"
}
```
API Gateway validates: "age" is expected to be an integer, but received a string. It returns a 400 Bad Request error with a message like: Invalid request body. The age field must be an integer.
Invalid Request (missing required field):
```
{}
```
API Gateway validates: "age" is a required field, but it’s missing. It returns a 400 Bad Request error with a message like: Invalid request body. The age field is required.
Invalid Request (extra field, if additionalProperties: false):
```
{
  "age": 30,
  "name": "Alice"
}
```
API Gateway validates: additionalProperties is set to false, and an unexpected property "name" was found. It returns a 400 Bad Request error with a message like: Invalid request body. Unrecognized field 'name'.

The beauty of this is that it offloads validation from your application code. Your Lambda function (or other backend service) can assume that the incoming payload is already well-formed and adheres to the defined schema. This simplifies your backend logic, reduces the attack surface, and provides consistent error responses to your API consumers.

The next hurdle you’ll likely encounter is handling dynamic path parameters like {userId} and ensuring they are also valid, which involves configuring "Request Parameters" in the same section.