Nylas errors and HTTP status codes

ℹ️ The v2-specific section on mail sync states has been moved. See the Account sync status documentation for this information.

This page is a reference list of API responses, error types, and HTTP status codes that you might encounter when working with Nylas.

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.

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.

For more information about specific error codes, see the following documentation:

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
    }
  }
}

HTTP status codes

Nylas uses a set of conventional HTTP response codes to indicate the success or failure of API requests.

HTTP Status Code	Description
`200` OK	Everything worked as expected.
`202` Not Ready	The request was valid, but the resource wasn't ready. Retry the request with exponential backoff.
`400` Bad Request	The request was malformed or missing a required parameter.
`401` Unauthorized	Could not verify access credentials. No valid API key or `access_token` was provided.
`402` Request Failed or Payment Required	The request parameters were valid, but the request failed or you must add a credit card to your organization.
`403` Forbidden	The request includes authentication errors, blocked developer applications, or cancelled accounts.
`404` Not Found	The requested item doesn't exist.
`405` Method Not Allowed	You tried to access a resource using an invalid method.
`410` Gone	The requested resource has been removed from the Nylas servers.
`413` Request Entity too Large	The transmitted data value exceeds the capacity limit for Send, v3 Attachments, or v2 Files requests.
`418` I'm a Teapot	🫖
`422` Sending Error	This response was returned during the sending process.
`429` Too Many Requests	Slow down! If you legitimately require this many requests, contact Nylas Support.
`500`, `502`, and `503` Server Errors	An error occurred in the Nylas server. If this persists, see the Nylas platform status page or contact Nylas Support.
`504` Provider Error	Wait and try again later. If the problem persists, check with your service provider.

⚠️ If you make a PUT request that contains no body content, Nylas returns a 400 Empty Request Body error.

For more information, see Wikipedia's list of HTTP status codes or the WebFX HTTP status codes database.