Nylas errors and HTTP status codes

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

You can also skip to the pages for more specific pages for error codes:

• 200-299 responses
• 400-499 responses
• 500-599 responses
• 700-799 responses

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.resource_blocked	423	Resource blocked, contact administrator.
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:

• 200-299 responses
• 400-499 responses
• 500-599 responses
• 700-799 responses

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.