# Nylas errors and HTTP status codes Source: https://developer.nylas.com/docs/api/errors/ 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](/docs/api/errors/200-response) - [400-499 responses](/docs/api/errors/400-response) - [500-599 responses](/docs/api/errors/500-response) - [700-799 responses](/docs/api/errors/700-response) ## 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](/docs/api/errors/200-response) - [400-499 responses](/docs/api/errors/400-response) - [500-599 responses](/docs/api/errors/500-response) - [700-799 responses](/docs/api/errors/700-response) ### Sample HTTP error response The following JSON snippet is an example of an HTTP error response that you might receive from Nylas. ```json { "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. ```json { "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 or Attachments requests. | | `418` I'm a Teapot | [🫖](https://en.wikipedia.org/wiki/Hyper_Text_Coffee_Pot_Control_Protocol) | | `422` Sending Error | This response was returned during the sending process. | | `429` Too Many Requests | Slow down! If you legitimately require this many requests and you have a contract with us, [contact Nylas Support](/docs/support/#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](https://status.nylas.com) or [learn how to get support](/docs/support/). | | `504` Provider Error | Wait and try again later. If the problem persists, check with your service provider. If you get an error caused by spam (for example, `554 5.7.1 nyla@example.com is sending SPAM`) don't try again. Check with your service provider instead. | > **Warn:** > **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](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) or the WebFX [HTTP status codes database](https://www.webfx.com/web-development/glossary/http-status-codes/).