# API Gateway での REST API のゲートウェイレスポンス
ゲートウェイレスポンスは、API Gateway によって定義されたレスポンスタイプで識別されます。レスポンスは、HTTP ステータスコード、パラメータマッピングで指定される追加のヘッダーのセット、および [VTL](https://velocity.apache.org/engine/devel/vtl-reference.html) 以外のマッピングテンプレートで生成されるペイロードで構成されます。
API Gateway REST API では、ゲートウェイレスポンスは [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) によって表されます。OpenAPI では、`GatewayResponse` インスタンスは [x-amazon-apigateway-gateway-responses.gatewayResponse](api-gateway-swagger-extensions-gateway-responses.gatewayResponse.md) 拡張子で記述されます。
ゲートウェイレスポンスを有効にするには、API レベルで[サポートされているレスポンスタイプ](supported-gateway-response-types.md)のゲートウェイレスポンスを設定します。API Gateway からこのタイプのレスポンスが返されるたびに、ゲートウェイレスポンスに定義されているヘッダーマッピングとペイロードマッピングテンプレートに適用されてマッピングされた結果が API 発信者に返されます。
次のセクションでは、API Gateway コンソールと API Gateway REST API を使用してゲートウェイレスポンスを設定する方法を示します。
## エラーレスポンスをカスタマイズするためのゲートウェイレスポンスのセットアップ
API Gateway は、受信リクエストを処理できない場合、統合バックエンドにリクエストを転送せずにクライアントにエラーレスポンスを返します。デフォルトでは、エラーレスポンスにエラーを説明する短いメッセージが含まれます。たとえば、未定義の API リソースに対してオペレーションを呼び出そうとすると、`{ "message": "Missing Authentication Token" }` というメッセージが含まれたエラーレスポンスが返されます。API Gateway に慣れていないユーザーには、メッセージの意味がわかりにくい場合があります。
一部のエラーレスポンスについては、API デベロッパーがカスタマイズして異なる形式で返すことが API Gateway で許可されています。たとえば、`Missing Authentication Token` の場合は、次の例に示すように、元のレスポンスペイロードにヒントを追加し、考えられる原因を説明できます: `{"message":"Missing Authentication Token", "hint":"The HTTP method or resources may not be supported."}`。
API が外部交換と AWS クラウドの間を仲介する場合は、統合リクエストまたは統合レスポンスの VTL マッピングテンプレートを使用して、ペイロードを 1 つの形式から別の形式にマッピングします。ただし、VTL マッピングテンプレートはレスポンスが正常に返される有効なリクエストに対してのみ使用できます。
無効なリクエストに対しては、API Gateway は統合を完全にバイパスしてエラーレスポンスを返します。エラーレスポンスを交換に準拠した形式にするには、カスタマイズを使用する必要があります。カスタマイズは、単純な変数の置換のみをサポートする VTL 以外のマッピングテンプレートでレンダリングされます。
API Gateway で生成されたエラーレスポンスを API Gateway で生成される任意のレスポンスに一般化したものは、*ゲートウェイレスポンス*と呼ばれます。これにより、API Gateway で生成されたレスポンスは統合レスポンスから区別されます。ゲートウェイレスポンスのマッピングテンプレートは、`$context` 変数の値と `$stageVariables` プロパティの値にアクセスできます。また、`method.request.param-position.param-name` 形式のメソッドリクエストのパラメータにもアクセスできます。
`$context` 変数の詳細については、「[データ変換のコンテキスト変数](api-gateway-mapping-template-reference.md#context-variable-reference)」を参照してください。`$stageVariables` の詳細については、「[ステージ変数](api-gateway-mapping-template-reference.md#stagevariables-template-reference)」を参照してください。メソッドリクエストパラメータの詳細については、「[入力変数](api-gateway-mapping-template-reference.md#input-variable-reference)」を参照してください。
**Topics**
+ [エラーレスポンスをカスタマイズするためのゲートウェイレスポンスのセットアップ](#customize-gateway-responses)
+ [API Gateway コンソールを使用して REST API のゲートウェイレスポンスをセットアップする](set-up-gateway-response-using-the-console.md)
+ [API Gateway REST API を使用してゲートウェイレスポンスを設定する](set-up-gateway-response-using-the-api.md)
+ [OpenAPI でゲートウェイレスポンスのカスタマイズを設定する](set-up-gateway-responses-in-swagger.md)
+ [API Gateway でのゲートウェイレスポンスタイプ](supported-gateway-response-types.md)