Add more error types to OAuth token request troubleshooting (github#36869)

Co-authored-by: skedwards88 <[email protected]>

Author: indigok

content/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app.md

@@ -136,3 +136,42 @@ You can generate a user access token with this method regardless of whether the
 By default, user access tokens expires after 8 hours. If you receive a user access token with an expiration, you will also receive a refresh token. The refresh token expire after 6 months. You can use this refresh token to regenerate a user access token. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens)."
 
 {% data variables.product.company_short %} strongly encourages you to use user access tokens that expire. If you previously opted out of using user access tokens that expire but want to re-enable this feature, see "[AUTOTITLE](/apps/maintaining-github-apps/activating-optional-features-for-github-apps)".
+
+## Troubleshooting
+
+The following sections outline some errors you may receive when generating a user access token.
+
+### Incorrect client credentials
+
+If the `client_id` or `client_secret` that you specify are incorrect, you will receive an `incorrect_client_credentials` error.
+
+To resolve this error, make sure to use the correct credentials for your {% data variables.product.prodname_github_app %}. You can find the client ID and client secret on the settings page for your {% data variables.product.prodname_github_app %}. For more information about navigating to your {% data variables.product.prodname_github_app %} settings page, see "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app-registration#navigating-to-your-github-app-settings)."
+
+### Redirect URI mismatch
+
+If you specify a `redirect_uri` that doesn't match one of the callback URLs in your {% data variables.product.prodname_github_app %} registration, you will receive a `redirect_uri_mismatch` error.
+
+To resolve this error, either provide a `redirect_uri` that matches one of the callback URLs for your {% data variables.product.prodname_github_app %} registration, or omit this parameter to default to the first callback URL that is listed on your {% data variables.product.prodname_github_app %} registration. For more information, see "[AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/about-the-user-authorization-callback-url)."
+
+### Bad verification code
+
+If you are using device flow and the verification code (`device_code`) that you specified is incorrect, expired, or doesn't
+match the value that you received from the initial request to `{% data variables.product.oauth_host_code %}/login/device/code`, you will receive a `bad_verification_code` error.
+
+To resolve this error, you should start the device flow again to get a new code. For more information, see "[Using the device flow to generate a user access token](#using-the-device-flow-to-generate-a-user-access-token)."
+
+### Bad refresh token
+
+If the refresh token that you specified is invalid or expired, you will receive a `bad_refresh_token` error.
+
+To resolve this error, you must restart the web application flow or device flow to get a new user access token and refresh token. You will only receive a refresh token if your {% data variables.product.prodname_github_app %} has opted in to expiring user access tokens. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens)."
+
+### Unsupported grant type
+
+When you request a user access token via the device flow, the `grant_type` parameter must be `urn:ietf:params:oauth:grant-type:device_code`. When you refresh a user access token by using a refresh token, the `grant_type` parameter must be `refresh_token`. If you don't use the correct grant type, you will receive an `unsupported_grant_type` error.
+
+### Unverified user email
+
+If the user for whom you are trying to generate a user access token has not verified their primary email address with {% data variables.product.company_short %}, you will receive an `unverified_user_email` error.
+
+To resolve this error, prompt the user to verify the primary email address on their {% data variables.product.company_short %} account. For more information, see {% ifversion fpt or ghec %}"[AUTOTITLE](/get-started/signing-up-for-github/verifying-your-email-address)."{% else %}"[AUTOTITLE](/free-pro-team@latest/get-started/signing-up-for-github/verifying-your-email-address)" in the  {% data variables.product.prodname_free_user %} documentation.{% endif %}

content/apps/oauth-apps/maintaining-oauth-apps/troubleshooting-oauth-app-access-token-request-errors.md

@@ -55,15 +55,6 @@ registered with your application.
 
 ## Bad verification code
 
-```json
-{
-  "add_scopes": [
-    "repo"
-  ],
-  "note": "admin script"
-}
-```
-
 If the verification code you pass is incorrect, expired, or doesn't
 match what you received in the first request for authorization you will
 receive this error.
@@ -78,3 +69,17 @@ receive this error.
 
 To solve this error, start the [OAuth authorization process again](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps)
 and get a new code.
+
+## Unverified user email
+
+If the user for whom you are trying to generate a user access token has not verified their primary email address with {% data variables.product.company_short %}, you will receive this error.
+
+```json
+{
+  "error": "unverified_user_email",
+  "error_description": "The user must have a verified primary email.",
+  "error_uri": "/apps/managing-oauth-apps/troubleshooting-oauth-app-access-token-request-errors/#unverified_user_email"
+}
+```
+
+To resolve this error, prompt the user to verify the primary email address on their {% data variables.product.company_short %} account. For more information, see {% ifversion fpt or ghec %}"[AUTOTITLE](/get-started/signing-up-for-github/verifying-your-email-address)."{% else %}"[AUTOTITLE](/free-pro-team@latest/get-started/signing-up-for-github/verifying-your-email-address)" in the  {% data variables.product.prodname_free_user %} documentation.{% endif %}