Only show these results:

Nylas API responses, 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.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.

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.