Monitoring for and handling errors in Nylas

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

We follow industry best practices by reporting on outage incidents as soon as a problem is identified. You can use our status page to track ongoing incidents and get real-time updates on our progress resolving them.

You’ll need to prepare your project to handle the following types of errors:

• Invalid credentials errors: Generated when an account’s OAuth token is expired or was revoked, or its password was changed.
• API errors: Generated when your project makes a request to the Nylas APIs and receives a non-200 response, or encounters a network error.

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

Monitor application health and status

Nylas constantly tracks a variety of metrics across the platform and alerts an on-call engineer if it detects irregularities.

Because Nylas is a core part of many projects, it’s a good practice to track errors coming from both your application and your 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 requests fail.

We strongly recommend keeping logs of the errors you encounter to help with troubleshooting and resolving issues.

Monitor for invalid credentials

Your users might need to re-authenticate with Nylas periodically to connect to their provider. When and how often they need to do this depends entirely on their provider’s policies. Until the user re-authenticates their grant, you can still use their access token to work with their synced data. Nylas can’t retrieve new data from their provider until they re-authenticate, though.

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

Monitor for API errors

Nylas follows the HTTP standard for status codes, and returns 200 OK responses when requests are completed without error. Other status codes, such as 4xx or 5xx errors, indicate that a request encountered an error.

The Nylas SDKs raise exceptions when requests aren’t successful. If you’re making your own HTTP requests, though, you should ensure your project checks status codes automatically.

Nylas returns a consistent JSON object on errors. Each error object includes a message fields that lists details about the error. You can see more information about API errors your project has encountered in the Nylas Dashboard by selecting Logs in the left navigation.

The majority of errors you might encounter are most likely transient. Usually, Nylas’ retry with exponential backoff approach is successful in resolving them. For more information, see our error code documentation.

Monitor for rate limits

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

Nylas returns a 429 error when an account hits one of Nylas’ rate limits. This prevents the account from making requests for a set amount of time. We recommend that you implement an exponential backoff strategy so accounts can recover and continue operating if they hit a rate limit.

Nylas is also subject to provider rate limits for the following activities:

• Sending messages: Nylas uses the email account associated with a grant to send messages through the user’s provider. Different providers have different send limits, but most users never hit these limits during regular activities.
• Creating and updating objects: Because create and update actions are very rare, you’re not likely to ever hit these limits.
• Message attachments, raw MIME content, and contact pictures: Nylas caches these objects 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 a long period of time, Nylas marks the destination as failed. This means that Nylas stops trying to send webhook notifications for your project until the problem is fixed. See Failing and failed webhooks for more information about failure limits and how Nylas sends failure notifications.