List of Cognito authentication error codes and messages

[joelzwarrington]

Is this related to a new or existing framework?

No response

Is this related to a new or existing API?

Authentication

Is this related to another service?

Cognito

Describe the feature you'd like to request

I would like to be able to find a list of common Cognito authentication error codes and messages so that I could provide a mapping for translation purposes.

Describe the solution you'd like

Either one of the following would be ideal:

• Typescript type for each method's error codes/messages
  • Added to https://github.com/DefinitelyTyped/DefinitelyTyped or this package

OR/AND

• Documentation article which provides this list of error codes/messages

---

So that I could do something like this:

try {
  await Auth.signIn(email, password);
} catch(error) {
  const { code, message }: { code: AuthSignInErrorCode | undefined, message: AuthSignInErrorMessage | undefined } = error;
  switch(code) {
    case AuthSignInErrorCode.USER_NOT_CONFIRMED: {
      // do something if user is not confirmed
    }
  }
}

Describe alternatives you've considered

I have considered encountering the errors myself manually and creating my own types, however I'm not aware of each of the errors

Additional context

No response

Is this something that you'd be interested in working on?

• 👋 I may be able to implement this feature request
• ⚠️ This feature might incur a breaking change

[jvliwanag]

Would love this as well. In the meantime, I hunt for the "code" part on each relevant Amazon Cognito API reference.

Example: https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html#API_SignUp_Errors

[sammartinez]

Thanks for the feature request on this @joelzwarrington. Are you looking for something like this? https://github.com/aws-amplify/amplify-js/blob/main/packages/auth/src/Errors.ts

[joelzwarrington]

Thanks for the feature request on this @joelzwarrington. Are you looking for something like this? https://github.com/aws-amplify/amplify-js/blob/main/packages/auth/src/Errors.ts

@sammartinez hello - I am looking for something similar to what you've shown. AuthErrorStrings is the only thing exported from @aws-amplify/auth top-level module, that does seem like a good thing to improve so that it covers more use cases.

I've started #9167, where I'll add all of the error messages I've encountered and a description of how I've encountered them so other developers implementing their custom UI can implement their our translation messages.

Additionally it would be nice to update/add a documentation article which links to AuthErrorStrings as a type that should be used to handle/verify errors

[joelzwarrington]

I am closing this issue as it's stale and didn't have any luck with the pull request, if you are looking to implement something like this, please feel free to mention me and can chat about it further 😄

[mkbctrl]

@joelzwarrington hey, did you by any chance find a solution to it yet? I am looking for a proper list of errors and errorCodes so I can map their messages and replace with custom text + handle some of them with dedicated actions.

If you don't have anything yet, I am willing to help, should be interesting.

cc: @jamesaucode do you also have any comments on that?

Edit:
Breadcrumb, but I can see some exceptions added at the bottom here:
https://github.com/aws-amplify/amplify-js/blob/08e01b1c09cfab73f2eb1b1b18fe1a696e2a028f/packages/amazon-cognito-identity-js/README.md

Maybe we can find smth there

[joelzwarrington]

Hey @mkbctrl 👋,

Our solution wasn't perfect, but we built our own enum with error codes so that we could give error messages/do other things as you've described. I started a PR with all of the errors we had encountered here: #9167

Because of the feedback from the Amplify team who didn't understand the ask/problem; I didn't waste my time continuing to try and improve the SDK. So we continued to use our own enums.

I no longer have access to the list of error codes that was built up to cover those use cases. I would also love to help, but don't use Cognito right now due to the lack of documentation/support, and have opted for other authentication services.

@ChristianLee-Jobber @linds14sr20det, perhaps you might be able to share those list of errors?

Another issue worth mentioning would be #8969

[mkbctrl]

Thanks for the quickest reply ever 🍻 great input!

Because of the feedback from the Amplify team who didn't understand the ask/problem

this is worrying... I would imagine this would add a lot of value to anyone implementing custom registration/login/reset views where designers have their own requirements.

I will have a look at your old PR, do some research on my own, maybe this time this issue will have more luck.
Let's see how it goes, I will keep you posted

[mkbctrl]

Btw: other authentication services, anything worth talking about?

[joelzwarrington]

@mkbctrl I've sent you an email!

[PhillipFraThailand]

+1

[wmoa]

+1

[wmoa]

@joelzwarrington What was your solution to map errors?

I was trying to do something like

if (e instanceof Auth.UsernameExistsException) {
  // do something
}

I just wasn't able to import the classes from Amplify, I don't think they are exposed.

[joelzwarrington]

@joelzwarrington What was your solution to map errors?

I was trying to do something like

if (e instanceof Auth.UsernameExistsException) {

  // do something

}

I just wasn't able to import the classes from Amplify, I don't think they are exposed.

@wmoa have a look at the issue description, there's a code block example. You'll have to define your own enum of error messages though

[wmoa]

@joelzwarrington woops, I skimmed this thread in a rush (it's been a long day), apologies.

That did the trick for now, thank you very much. 😄

[mkbctrl]

I ended up with a hook returning keyed object like that, here's an example:

export const useAuthErrors = () => {
  const { t } = useTranslation('auth')

  const errorMap: Record<
    string,
    {
      message: string
      action: null | ((email?: string) => void)
    }
  > = {
    /** Thrown by amplify when email or password doesn't match */
    /** FIXME: The same exception is returned when you try to confirm already confirmed account */
    NotAuthorizedException: {
      message: t('validator.accountCredentialsInvalid'),
      action:() => {
        ...perform an action (optional) like a redirect or displaying toast
      },
    },
  }

  return {
    errorMap,
  }
}

This way I am able to translate the errors easily and control what will be displayed to the user + side effects

[ghost]

Something definitely has to be done about this. I also had to create my own enum based on the errors returned by the underlying cognito APIs

[nadetastic]

Hi @abdulramonjemil, we are currently working on improving our typescript support for the library, and I recommend that you take a look at the Typescript Improvements RFC.

As part of the initiative, the plan is to throw AuthError which will map to the service errors, and you will not need to create ENUMs.

If you have any comments or feedback, please provide them on the Linked RFC above. Thanks!

[ghost]

Just checked out the linked RFC, and it looks great.

[IamCocoDev]

Hello,

I would like to request a feature to provide a comprehensive list of Cognito authentication error codes and messages. This would be helpful for developers who need to handle and translate common authentication errors for better user feedback.

Ideally, the solution could include:

Typed definitions for error codes and messages for each Cognito method.
Addition of the list to the DefinitelyTyped repository (https://github.com/DefinitelyTyped/DefinitelyTyped) or a dedicated package.
Alternatively, a documentation article providing the list of error codes and messages would be sufficient.
Having access to this information would allow developers to handle Cognito authentication errors more effectively and provide accurate feedback to users in their preferred language.

Thank you for considering this feature request.

[cwomack]

Hello, @IamCocoDev and thanks for the feedback. Would you mind leaving your comments on our TypeScript Improvements RFC where feature requests and improvements are being consolidated for Amplify JS?

Thank you!

[IamCocoDev]

I'm sure I'll add one more comment to the #11113 thread. Thank you very much for your quickly answering.

This will greatly improve development for people in LATAM. It will help build more user-friendly interfaces.

Have a nice week @cwomack

[JDMathew]

@joelzwarrington , I would be interested to know what authentication service you switched to. I'm working with amplify but it's to much hassle for the lack of support / lock-in. Handle errors feels fundamental to authentication. It doesn't look like v6 will be out anytime soon either.

[joelzwarrington]

Hey @JDMathew, appreciate that you'd like my opinion/recommendation... however this thread is not the place for that discussion.

You're always welcome to reach out at my personal email address if you'd like to chat!

[JacobDel]

fyi this is the list with error codes: https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html#API_SignUp_Errors
seems like we have to hardcode these ourselves and hope they won't change too much over time

[joelzwarrington]

fyi this is the list with error codes: https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html#API_SignUp_Errors seems like we have to hardcode these ourselves and hope they won't change too much over time

@JacobDel, unfortunately that list doesn't capture all error codes, just ones for sign-up. But getting them from there is a good start 😄

[lewisdonovan]

+1 It's wild that we don't have types for this