Inconsistencies in response codes depending on whether API Gateway response settings are configured

Question

I launched a Lambda function with a concurrent execution limit and the associated API Gateway.

At this point, all Response fields in Gateway Responses are set to their default values.\
In this state, when I sent a request that exceeded the concurrent connection limit, a 500 status code was returned.

```
"status": 500,
    "body": "{\"message\": \"Internal server error\"}",
    "headers": {
        "x-amzn-ErrorType": "InternalServerErrorException"
    },
    "multiValueHeaders": {
        "x-amzn-ErrorType": [
            "InternalServerErrorException"
        ]
    },
```
After this, when making arbitrary corrections to the “Integration failure” in the Gateway responses, setting the Response to a custom status, and then resending the same request, a 504 error will be returned (without redeploying API Gateway).

```
{
    "status": 504,
    "body": "{\"message\":\"Customed response\"}",
    "headers": {
        "x-amzn-ErrorType": "InternalServerErrorException"
    },
    "multiValueHeaders": {
        "x-amzn-ErrorType": [
            "InternalServerErrorException"
        ]
    },
```
Finally, after deleting the custom response and resubmitting the request, the 500 status code started appearing again.

I’d like to understand the reasoning behind this behavior.
In particular,
- Can a 500 error occur in custom mode?
- Can a 504 error occur in default mode?

I’m concerned about the consistency of these responses.

re:Post Agent · Answer

The behavior you're observing is related to how API Gateway handles gateway responses and their default configurations. Let me explain what's happening:

API Gateway provides gateway response types that can be customized, including `INTEGRATION_FAILURE` and `DEFAULT_5XX`. The `INTEGRATION_FAILURE` response type has a default status code of 504, while `DEFAULT_5XX` serves as a fallback gateway response for unspecified 5XX response types with a null default status code.

When all Response fields are set to their default values (uncustomized state), API Gateway may return a 500 status code because the `DEFAULT_5XX` gateway response is being used as the fallback. This fallback has a null status code by default, which can result in a 500 error being returned.

When you customize the "Integration failure" gateway response with a custom status code, API Gateway starts using the `INTEGRATION_FAILURE` response type explicitly, which has a default status code of 504. This is why you see the 504 error after making the customization, even without redeploying.

When you delete the custom response, the system reverts to using the `DEFAULT_5XX` fallback behavior again, which explains why you see the 500 status code return.

To answer your specific questions:
- A 500 error can occur in "default mode" when the `DEFAULT_5XX` fallback response is being used
- A 504 error occurs when the `INTEGRATION_FAILURE` gateway response type is explicitly configured or triggered, as 504 is its default status code

The key insight is that changing the status code of `DEFAULT_5XX` affects all other 5XX responses, and resetting it to null reverts other 5XX responses to their original values. This explains the consistency behavior you're experiencing - the system is working as designed, switching between the specific `INTEGRATION_FAILURE` response type (504) and the general `DEFAULT_5XX` fallback (500) based on your configuration.  
**Sources**  
[Gateway response types for API Gateway - Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/supported-gateway-response-types.html)

Mohamad El Bohsaly · Answer

## Direct Answers

- **Can a 500 occur with a custom `Integration failure` response?**  
  Yes, if the error is **not** an integration failure (e.g., Lambda code error, timeout, or API configuration error) and you haven’t customized `DEFAULT_5XX`.

- **Can a 504 occur with default Gateway Responses?**  
  Yes – the **default** status for `Integration failure` is `504`.  
  If you saw `500` in default mode, the error was likely a **different 5XX** (e.g., Lambda unhandled exception). A true concurrency throttle is `Integration failure` → default `504`.

## Why You Saw Inconsistent Responses

1. **First request (500)** – Probably a Lambda invocation error (e.g., cold start bug, not a throttle).  
2. **After customizing `Integration failure` to 504** – A real throttle now returns your custom 504.  
3. **After deleting custom response** – API Gateway falls back to default `504` for `Integration failure`. If you see `500` again, the error type changed back to a generic 5XX (check Lambda logs).

## How to Make It Consistent (CLI / Console)

### ✅ Via Console
1. Go to API Gateway → your API → **Gateway Responses**.
2. Edit **`Integration failure`** → set status code to `503` or `429` (recommended for throttles).
3. Edit **`DEFAULT_5XX`** → set status code to `500` (or your preferred fallback).
4. **Redeploy** the API.

### ✅ Via CLI
```bash
# Get response ID for Integration failure
aws apigateway get-gateway-responses --rest-api-id

# Update Integration failure to return 429 (custom body optional)
aws apigateway update-gateway-response \
    --rest-api-id  \
    --response-type INTEGRATION_FAILURE \
    --patch-operations op=replace,path=/statusCode,value='429'

# Redeploy
aws apigateway create-deployment --rest-api-id  --stage-name

Inconsistencies in response codes depending on whether API Gateway response settings are configured

Direct Answers

Why You Saw Inconsistent Responses

How to Make It Consistent (CLI / Console)

✅ Via Console

✅ Via CLI

Add your answer

Relevant content