AWS 提供サービスのご多分に漏れずAmazon Cognitoも求める情報を膨大な公式ドキュメントの中から得るのに骨が折れます。Cognito はユースケースが幅広いこともありその苦労もひとしお。特に苦労したのはエラー応答に関する情報で、まとまっているのを Web ではあまり見かけないように思うので、自分用の整理も兼ねてメモしておきます。
Cognito のエラーハンドリングが必要になるパターンは典型的には次かと思います。
- URL 指定で直接アクセスしたとき
- API Gateway のオーソライザーに設定したとき
- 各種 SDK でアクセスしたとき
以下それぞれについて。
URL 指定で直接アクセスしたとき
URL アクセスでエラーが発生したときはエラー型情報とエラーメッセージが HTTP レスポンスヘッダーとレスポンスボディそれぞれに設定されます。HTTP レスポンスヘッダーは次。
- エラー型情報 -
x-amzn-errortype - エラーメッセージ -
x-amzn-errormessage
レスポンスボディは JSON で次のかたちになります。
{
"__type": , "NotAuthorizedException",
"message": "Incorrect username or password"
}
API Gateway のオーソライザーに設定したとき
Cognito をオーソライザーに設定したAPI Gateway API で認証エラーとなったときはメッセージのみが HTTP レスポンスヘッダーとレスポンスボディそれぞれに設定されます。HTTP レスポンスヘッダーは次。
- エラーメッセージ -
x-amzn-errormessage
レスポンスボディは次。
{
"message": "Incorrect username or password"
}
各種 SDK でアクセスしたとき
各種 SDK でアクセスしたときはそれぞれの SDK のエラー / 例外フォーマットに変換されることと思います。たとえばAWS SDK for Python(Boto3)だとドキュメントに記されている例外として送出されます。
ただし「Amazon Cognito は E メール送信数超過でエラー LimitExceededException を返す」で記したようなドキュメント化されていないエラーは対応する既存の例外型が存在しないため式を伴うexcept節では捕捉できません。そうした例外に対応するためにはError handling - Boto3 1.28.1 documentationで説明されているように式を伴わないexcept節で error.responseのプロパティを参照する必要があります。