Menu
Amazon API Gateway
Developer Guide

Gateway Response Types

API Gateway exposes the following gateway responses for customization by API developers.

Gateway response type Default status code Description
DEFAULT_4XX Null

The default gateway response for an unspecified response type with the status code of 4XX. Changing the status code of this fallback gateway response changes the status codes of all other 4XX responses to the new value. Resetting this status code to null reverts the status codes of all other 4XX responses to their original values.

DEFAULT_5XX Null

The default gateway response for an unspecified response type with a status code of 5XX. Changing the status code of this fallback gateway response changes the status codes of all other 5XX responses to the new value. Resetting this status code to null reverts the status codes of all other 5XX responses to their original values.

ACCESS_DENIED 403

The gateway response for authorization failure; for example, when access is denied by a custom or Amazon Cognito authorizer. If the response type is unspecified, this response defaults to the DEFAULT_4XX type.

API_CONFIGURATION_ERROR 500

The gateway response for invalid API configuration, including invalid endpoint address submitted, Base64 decoding failed on binary data when binary support is enacted, or integration response mapping cannot match any template and no default template is configured. If the response type is unspecified, this response defaults to the DEFAULT_5XX type.

AUTHORIZER_CONFIGURATION_ERROR 500

The gateway response for failing to connect to a custom or Amazon Cognito authorizer. If the response type is unspecified, this response defaults to the DEFAULT_5XX type.

AUTHORIZER_FAILURE 500

The gateway response when a custom or Amazon Cognito authorizer failed to authenticate the caller. If the response type is unspecified, this response defaults to the DEFAULT_5XX type.

BAD_REQUEST_PARAMETERS 400

The gateway response when the request parameter cannot be validated according to an enabled request validator. If the response type is unspecified, this response defaults to the DEFAULT_4XX type.

BAD_REQUEST_BODY 400

The gateway response when the request body cannot be validated according to an enabled request validator. If the response type is unspecified, this response defaults to the DEFAULT_4XX type.

EXPIRED_TOKEN 403

The gateway response for an AWS authentication token expired error. If the response type is unspecified, this response defaults to the DEFAULT_4XX type.

INTEGRATION_FAILURE 504

The gateway response for an integration failed error. If the response type is unspecified, this response defaults to the DEFAULT_5XX type.

INTEGRATION_TIMEOUT 504

The gateway response for an integration timed out error. If the response type is unspecified, this response defaults to the DEFAULT_5XX type.

INVALID_API_KEY 403

The gateway response for an invalid API key submitted for a method requiring an API key. If the response type is unspecified, this response defaults to the DEFAULT_4XX type.

INVALID_SIGNATURE 403

The gateway response for an invalid AWS signature error. If the response type is unspecified, this response defaults to the DEFAULT_4XX type.

MISSING_AUTHENTICATION_TOKEN 403

The gateway response for a missing authentication token error, including the cases when the client attempts to invoke an unsupported API method or resource. If the response type is unspecified, this response defaults to the DEFAULT_4XX type.

QUOTA_EXCEEDED 429

The gateway response for the usage plan quota exceeded error. If the response type is unspecified, this response defaults to the DEFAULT_4XX type.

REQUEST_TOO_LARGE 413

The gateway response for the request too large error. If the response type is unspecified, this response defaults to the DEFAULT_4XX type.

RESOURCE_NOT_FOUND 404

The gateway response when API Gateway cannot find the specified resource after an API request passes authentication and authorization, except for API key authentication and authorization. If the response type is unspecified, this response defaults to the DEFAULT_4XX type.

THROTTLED 429

The gateway response when usage plan-, method-, stage-, or account-level throttling limits exceeded. If the response type is unspecified, this response defaults to the DEFAULT_4XX type.

UNAUTHORIZED 401

The gateway response when the custom or Amazon Cognito authorizer failed to authenticate the caller.

UNSUPPORTED_MEDIA_TYPE 415

The gateway response when a payload is of an unsupported media type, if strict passthrough behavior is enabled. If the response type is unspecified, this response defaults to the DEFAULT_4XX type.