Error types in Nylas

This page is a reference list for error types that you might encounter when working with Nylas v3. For more information, see Nylas API responses, errors, and HTTP status codes.

Error types

Error messages include a JSON object that contains a standard set of attributes, including the error's type and a human-readable message string. These are designed to make debugging easier and allow for you to handle different scenarios that produce the same HTTP error code.

The table below shows the error types you might encounter while working with Nylas.

Error Type	HTTP Code	Default Message
`api.authentication_error`	`401`	Unauthorized
`api.internal_error`	`500`	Internal error, contact administrator.
`api.invalid_request_error`	`400`	Bad request
`api.invalid_request_payload`	`400`	Invalid JSON payload format.
`api.provider_error`	`504`	Provider error message. (Specific Provider HTTP code response possible.)
`api.not_found_error`	`404`	Resource not found.
`api.partial_not_found_error`	`404`	Partially missing data from requested resource(s).
`api.partial_success_error`	`504`	One or more objects could not be handled. (Specific Provider HTTP code response possible.)
`api.rate_limit_error`	`429`	Rate limit error.
`token.unauthorized_access`	`400`	Invalid API key.
`token.exchange_failed`	`400`	OAuth 2.0 token exchange failed.
`grant.callback_uri_not_allowed`	`400`	`callback_uri` is not allowed for this connector.
`grant.login_id_invalid`	`400`	Login ID or request is invalid or has expired.
`grant.not_found`	`404`	Grant not found.
`grant.refresh_token_invalid`	`401`	Invalid `refresh_token` supplied to Grant.
`grant.provider_required`	`400`	Provider field is required.
`grant.reauth_email_invalid`	`400`	Email addresses did not match during re-authentication.
`grant.scopes_conflict`	`400`	Some requested scopes were not included in the completed hosted auth, resulting in denied authentication.
`grant.gmail_domain_invalid`	`400`	Gmail domain is not allowed, resulting in denied authentication.
`grant.access_denied`	`403`	Access to Grant denied.
`grant.invalid_authentication`	`400`	Authentication failed due to wrong input or credentials.
`grant.provider_not_responding`	`400`	Provider not responding.
`grant.auth_limit_reached`	`400`	Maximum number of retries reached for hosted auth.
`grant.imap_type_mismatch`	`400`	IMAP provider mismatch.
`grant.provider_mismatch`	`400`	Grant provider mismatch.
`grant.imap_autodetect_fail`	`400`	IMAP auto-detection failed. Please provide additional IMAP configuration (host, port).
`grant.hosted_login_expired`	`400`	Hosted login expired.
`grant.session_revoke_failed`	`400`	Session revoke failed.
`grant.provider_id_token_missing`	`400`	Provider did not return ID token for authorized account.
`connector.not_found`	`404`	Connector not found.
`connector.provider_not_supported`	`400`	Provider invalid or not supported.
`connector.provider_settings_invalid`	`400`	Provider settings not supported.
`connector.provider_settings_secret_required`	`400`	Provider settings and Secret both are required if one needs to change.
`connector.already_exists`	`400`	Connector already exists.
`connector.problem`	`400`	Issues found with connector's settings or configuration.
`credential.not_found`	`404`	Credential not found.
`credential.already_exists`	`400`	Credential with this name for given connector already exists.
`credential.missing_param`	`400`	Credential is missing some essential values in its settings.
`connector.no_longer_exists`	`400`	Connector no longer exists.
`oauth2.provider_code_request_failed`	`400`	Provider refused to return `refresh_token` using code.
`oauth2.oauth_failed`	`400`	Hosted OAuth failed due to rejection by provider or user refusing consent.
`oauth2.invalid_client`	`400`	OAuth client not found.
`oauth2.invalid_grant`	`400`	Error creating grant with provided OAuth parameters.
`oauth2.redirect_uri_mismatch`	`400`	Redirect URI not allowed.
`oauth2.unsupported_grant_type`	`400`	Invalid `grant_type`.
`oauth2.invalid_token`	`401`	Token expired or revoked.
`oauth2.oauth_provider_error`	`400`	Error from OAuth 2.0 provider.
`oauth2.origin_not_allowed`	`400`	Error origin not allowed for `callback_uri` for `platform:js`.
`oauth2.provider_code_exchange_failed`	`403`	Code exchange to get access/refresh token failed on provider's side.
`application.missing_required_parameter`	`400`	One of the platform's required parameters is missing.
`application.not_found`	`404`	Application not found.
`application.callback_uris_not_found`	`404`	Application's redirect URIs not found.
`application.callback_uri_is_not_valid`	`400`	Application's redirect URI is not valid.
`application.id_not_allowed`	`403`	Application ID not allowed.
`common.scope_not_allowed`	`400`	One or more provided scopes is not allowed.
`common.secret_not_found`	`404`	Searched Secret record not found.
`v3_migration.account_to_grant_migration_failed`	`400`	Account migration to a V3 grant failed.
`v3_migration.translate_resource_failed`	`400`	Failed to translate Nylas resource ID to Provider resource ID.
`v3_migration.link_apps_failed`	`400`	Failed to link v2 & v3 applications.
`v3_migration.app_import_failed`	`400`	Failed to import v2 application's settings to v3 application.
`v3_migration.job_start_failed`	`400`	Failed start migration jobs.
`v3_migration.get_jobs_failed`	`404`	Failed to get info of migration jobs.

Sample HTTP error response

The following JSON snippet is an example of an HTTP error response that you might receive from Nylas.

{
  "request_id": "1f58962d-9967-42de-9dd3-3f55aa1a216a",
  "error": {
    "type": "invalid_request_error",
    "message": "The message_id parameter is required."
  }
}

Sample HTTP provider error response

HTTP errors include the provider_error parameter only when they're generated by the provider or connector, as in the following example.

{
  "request_id": "1f58962d-9967-42de-9dd3-3f55aa1a216a",
  "error": {
    "type": "invalid_request_error",
    "message": "The message_id parameter is required.",
    "provider_error": {
      // Provider error response
    }
  }
}