Skip to content
Docs
or

Troubleshooting Auth Errors

This article highlights most frequent errors that might occur during OAuth 2.0 integration. All error responses have the same structure and look like following sample:

{
  "success": false,
  "error": {
    "type": "app_id_not_allowed",
    "http_code": 400,
    "event_code": 702,
    "message": "Application ID not allowed",
    "request_id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47"
  }
}

Integration Errors

You only need to create an Integration once per provider and environment. If you haven’t created Integration yet, continue reading this section. In case you attempt to create another integration with the same client_id and client_secret pair integration_already_exists error will be returned. Please, make GET request to connect/integrations to retrieve the list of integrations.

The most common errors that happen working with integration are redirect_uri_not_allowed and scopes_conflict.

  • redirect_uri_not_allowed(event_code: 25003): Indicates invalid redirect URI specified for connect/auth request. This could happen if invalid (or mistyped) URI specified in constants files.
  • scopes_conflict(event_code: 25016): Indicates that some of the requested scopes were not included for connect/auth request. This could happen if scopes are invalid or missing. You are allowed to put multiple scopes in one line using comma and whitespace as a delimiter.

For more integration errors please visit Even Codes page.

During user consent flow user might deny requested permissions(scopes) or abort entire flow. In those cases flow returns oauth_failed error in URL like:

scheme://host/path?error=oauth_failed&error_code=45002&error_description=Hosted+OAuth+failed+due+to+rejection+by+provider+or+user+refusing+consent&state=123

Basically flow keeps the same error format but presents error object properties as query parameters in URL. Applications are required and strongly recommended to handle these errors gracefully in order to provide the best user experience.

PKCE Errors

PKCE is a OAuth 2.0 flow that provides extra level of security using SHA256 encryption mechanisms. One of the most popular and confusing errors is invalid_grant (event_code: 45004).

{
  "error": "invalid_grant",
  "error_code": 45004,
  "error_description": "Error creating grant with provided OAuth params",
  "error_uri": "https://accounts.nylas.io/#tag/Event-Codes",
  "request_id": "25c08995-a729-45d6-be2c-1de030f7a567"
}

This error indicates that grant could not be created with provided parameters. In order to troubleshoot this error check next things:

  1. Make sure your code_verifier parameter is less or equal to 256 characters long.
  2. Make sure your code_challenge is using SHA256 encryption.
  3. Make sure your are correctly doing base64 encoding with removed padding on code_challange before including this into API request.