Version:
Only show these results:

Error handling best practices

Although the Nylas APIs are highly available and robust, there's always a chance that you'll encounter errors when you're using them. Most errors are transient, and Nylas' retry with exponential backoff approach is successful. Nylas works hard to ensure outage incidents and transient errors from providers don't require intervention on your part.

🔍 Nylas follows industry best practices by reporting on outage incidents as soon as a problem is identified. You can use the Nylas status page to track ongoing incidents and get real-time updates on progress.

You will need to handle the following types of errors:

  • Invalid credentials errors: Thrown when an account's OAuth token is expired or was revoked, or its password was changed.
  • API errors: Thrown when your application makes a request to the Nylas API and you receive a non-200 HTTP status code response, or encounter a network error.
  • Account sync errors: Persistent errors that prevent Nylas' sync engine from retrieving the latest changes from a provider, or writing new changes to a provider.

This page describes strategies that Nylas recommends to mitigate and resolve any errors you may come across.

Monitor application health and status with instrumentation

You can track the health and status of your production application by setting up instrumentation. This helps you be proactive, enabling you to detect and resolve issues before they impact your end users.

Nylas constantly tracks different metrics across the platform, and alerts an on-call engineer in the event of irregularities.

Because Nylas is a core part of many applications, it's a good practice to track errors coming from both your app and the Nylas integration. This lets you detect any problems that may arise. For example, you can track the success rate of requests sent to the Nylas APIs and alert if a certain percentage of those requests fail. You should also keep logs of the errors you encounter to help with troubleshooting and resolving issues.

Monitor for invalid credentials

Your end users may need to re-authenticate with Nylas periodically to connect to their email provider. When and how often they need to re-authenticate depends entirely on their provider's policies. When this happens, you can still use the Nylas access token to access an end user's synced data, but Nylas cannot retrieve new data from the provider until the user re-authenticates their account.

You can check if an account's credentials are invalid using the account.invalid notification trigger, or by regularly querying the Account Management endpoints. You should prompt users to re-authenticate as soon as their accounts are flagged by Nylas as having invalid credentials.

If an end user originally authenticated their account by providing a username and password, they need to re-authenticate only when their password changes.

Monitor for API errors

Nylas follows the HTTP standard for status codes.

The Nylas APIs return a 200 OK response when requests are completed without error. Other status codes, such as 4xx or 5xx, indicate that the request encountered an error.

📝 Note: The Nylas SDKs raise exceptions when requests are not successful. If you're making your own HTTP requests, however, you may need to check status codes in your code.

Nylas returns a consistent JSON object on errors, which includes a message field that provides details about the error. You can also view more information about API errors in the Nylas Dashboard. The majority of errors are most likely transient, and Nylas' retry with exponential backoff approach is successful. For more information, see our error code documentation.

Monitor for rate limiting

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

The Nylas API returns a 429 HTTP status code when an account hits the rate limit; this prevents additional requests from being completed. Nylas recommends that you implement an exponential backoff strategy so accounts can recover and continue operating if they hit a rate limit. For more information, see our rate limits documentation.

Nylas is also subject to rate limiting from email providers for the following activities:

  • Sending email: Nylas uses an end user's authenticated email account to send email messages through their provider. Different providers have different send limits, but most people never hit these limits during regular use.
  • Updating and creating objects: Because create and update actions are very rare, you're not likely to ever hit these rate limits.
  • Requests to the /search endpoint: Nylas proxies requests to its /search endpoint to the end user's provider, so these requests are subject to provider rate limits. The activity is read-only, however, and is not likely to hit rate limits.
  • Message attachments, raw mime, and contact pictures: Nylas caches these items internally in Amazon S3 for seven days. Requests for this data after the seven-day period require Nylas to fetch the data from the provider.

Monitor for missed notifications

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

If you experience an outage, you can query for data that was modified since the first deliverability failure.

Monitor for account sync errors

Nylas syncs end users' accounts automatically. In the rare event that Nylas encounters persistent sync errors, it can prevent Nylas from retrieving the latest changes from a provider, or writing new changes to a provider. Nylas raises these errors using webhooks, or by reporting to the Account Management endpoints.

Accounts that receive persistent sync 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 by following the steps below. If you work through all of the steps and the issue persists, contact Nylas Support for help.

⚠️ Nylas keeps logs for two weeks only, so it's important to get help quickly if sync issues persist.

Restart account sync process

You can create an automation in your app to try to restart the account sync process when you get an account.stopped or account.sync_error status.

To restart the account sync process, use the following cURL commands.

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

Re-authenticate the account

You can create an automation in your app to ask an end user to re-authenticate their account when you get an account.stopped or account.sync_error status. You might do this as a second step if your restart automation doesn't work:

  1. Ask the end user to re-authenticate their account using either an email or an in-app message.
  2. As a good security practice, revoke the user's old access token.
  3. Wait for the end user to re-authenticate their account, then check the account status again.
    • If the account status is Running, the issue has been fixed.
    • If the account status is Partial, check again later. This status is temporary and will transition to either Running or Stopped.
    • If the account status is Stopped, contact Nylas Support.

When to contact Nylas Support

If following the troubleshooting steps does not solve account sync issues, contact Nylas Support or your sales representative. Have the following information at hand to help make troubleshooting as quick as possible:

  • Sync logs.
  • Whether the affected end user changed any settings.
  • The error that the affected end user is receiving.
  • The Account-ID, Message-ID (if applicable), and timestamps (if applicable).
  • Any troubleshooting that you've done so far.
  • Any code (if applicable).
  • Any details that can help Nylas reproduce the error (if applicable).

Get your sync logs

Follow these steps to get your sync logs:

  1. Log in to the Nylas Dashboard and select Accounts from the left navigation menu.
  2. Select the account that is having the sync issue.
  3. View the account's sync logs and note the error.

If the error suggests additional fixes or troubleshooting steps, try those before you contact Nylas Support.