Only show these results:

Error Handling and Monitoring

Even though Nylas has a highly available and robust API, there’s always a chance that you’ll encounter errors. Most errors are transient, and Nylas's retry with exponential backoff approach is successful. Nylas works hard to make sure outage incidents or transient errors from the providers don’t require intervention on your part. The types of errors you will need to handle are below.

  • Invalid Credentials - when an accounts' OAuth token is expired, was revoked, or their password was changed.
  • API errors - when your application makes a request to the Nylas API and you get a non-200 HTTP status code response or a network error.
  • Account sync errors - persistent errors that prevent our sync engine from getting the latest changes from the provider or writing new changes to the provider.

Nylas status

Nylas follows industry best practices to report on outage incidents as soon as a problem is identified, so you can identify when issues arise from your code or from upstream infrastructure. See the Nylas status page to track ongoing incidents and get real-time updates on progress.

Setting up instrumentation

Instrumentation on a production application can track the health and status, and help you be proactive so you can detect and resolve issues before them impact end-users. Nylas constantly tracks different metrics across the platform, and alerts an on-call engineer in the event of irregularities.

Nylas is a core part of many applications, and it's a good practice to track errors both coming from your application, and from the Nylas integration to detect any problems. For example, you could tracking the success rate of requests to Nylas, and alert if a certain percentage of requests fail.

You should also keep logs of errors you encounter to help with troubleshooting and resolving issues.

Monitoring for invalid credentials

Users might periodically need to re-authenticate with Nylas to connect to their email provider. When and how often they need to re-authenticate depends entirely on the provider’s policies. It's the same as if you have a Google or Microsoft account that gets signed out of your browser.

When this happens, you can still use the Nylas access token to access data that was already synced, but Nylas cannot retrieve new data from the provider until the account re-authenticates.

You can check if an account’s credentials are invalid using the account.invalid webhook trigger, or by regularly querying the Account Management endpoints. You should prompt the user to re-authenticate as soon as the account is flagged by Nylas as invalid credentials status.

If users originally authenticated by providing a username and password, then they only need to re-authenticate when their password changes.

Monitoring for API errors

Nylas follows the HTTP standard for status codes and we return a 200 success when requests complete without error. Other status codes, such as 4xx or 5xx indicate there was an error. Our SDKs will raise exceptions when requests aren’t successful, but if you’re making your own HTTP requests, you may need to check status codes in your code.

Nylas returns a consistent JSON object on errors with a message field that provides details about the error. You can also view more information about API errors in the developer dashboard. The majority of errors are most likely transient and retrying with exponential backoff will be successful. For more information, see our reference on different errors that Nylas may return.

Monitoring for rate limiting

Nylas rate limiting prevents a single account from affecting the reliability or performance of other accounts on the platform. The Nylas rate limits are generous so the API can accommodate any use case you can think of.

The Nylas API returns a 429 HTTP status code when you hit rate limiting, and this prevents additional requests from completing. You should implement an exponential backoff strategy so that accounts can recover and continue operating if it hits a rate limit. See the developer guide on rate limiting for more information.

Nylas is also subject to rate limiting from the providers in the following activities.

  • Sending email - Nylas uses the authenticated email account to send email through the provider. Different providers have different send limits, but most people never hit these limits.
  • Updating and Creating objects - While these rate limits exist, you are unlikely hit them, because create and update actions are very rare.
  • /search endpoint - Nylas proxies requests to its search endpoint to the provider, so they are subject to provider limits. However, the activity is read-only and unlikely to hit rate limits.
  • Message attachments, raw mime, contact pictures - Nylas caches these items for seven days internally in Amazon S3. Requests for this data after this period require Nylas to fetch the data from the provider.

Missed webhooks

If your webhook server fails for long periods of time, Nylas marks your webhook as failed. This means that Nylas stops trying to send webhooks for your entire application until the problem is fixed. See the Retry attempt documentation for more information about failure limits, and how Nylas sends failure notifications.

If you experience an outage, you can re-run missed webhooks from the outage period (within 14 days) using the Nylas delta endpoints.

Monitoring for account sync errors

Nylas syncs accounts automatically, but in the rare event that Nylas encounters persistent errors, it can halt changes from the provider. Nylas raises these errors using webhooks or by reporting to the account management endpoints. Accounts that are receiving persistent errors are marked as either account.stopped or account.sync_error.

Troubleshooting stopped accounts

Most of the time, you can resolve account sync errors on your own. The steps to fix a stopped account are described below. If you work through all of these steps without success, contact Nylas Support for more help.

Restart the account sync

You can create an automation in your app to automatically try to restart a sync process when you get an account.stopped or account.sync_error status. Nylas only keeps logs for two weeks, so it's important to get help quickly if sync issues persist.

You can use the curl command below:

curl -X POST -u YOUR_APP_SECRET https://api.nylas.com/a/YOUR_APP_ID/accounts/ACCOUNT_ID/downgrade
curl -X POST -u YOUR_APP_SECRET https://api.nylas.com/a/YOUR_APP_ID/accounts/ACCOUNT_ID/upgrade

If you tried this and it didn't work, go on to the next step.

Re-authenticate the account

You can also create an automation to immediately ask the user to re-authenticate when you get a Stopped Sync status. You might do this as second step if your restart automation doesn't work.

  1. Ask the customer to re-authenticate their account using one or both of the following methods:
    • Send them an email asking to re-authenticate.
    • Send them an in-app message asking them to re-authenticate.
  2. Revoke their old token as a good security practice.
  3. Wait for the user to re-authenticate.
  4. Once the user re-authenticates, check the account status again.
    • If it's in Running, then the issue is fixed.
    • If it's in Partial, try again later. This status is temporary and transitions to either Running or Stopped.
    • If it's in Stopped even after the user re-authenticates, contact Nylas Support.

When to contact Nylas Support

If restarting and re-authenticating do not solve the account sync issues, contact Nylas Support or your sales representative.

Have the following information available when you contact Support to speed up troubleshooting:

  • Get your sync logs: From the Nylas Dashboard, click Accounts, and select the account that's having the sync issue. View the Sync Logs and note the error. If the error suggests additional fixes or troubleshooting steps, try those before contacting support.
  • Ask the end user if they changed any settings, and for the exact error they see.
  • Include the following details in your email to speed up the troubleshooting:
    • Account-ID
    • Message-ID (if applicable)
    • Timestamps (if applicable)
    • Any errors you see in the sync log
    • Any troubleshooting you've done so far
    • Information about the error the end-user sees
    • Include any code (if applicable)
    • Any details that can help us reproduce the error (if applicable)