Client error responses: 400–499

Nylas returns 400 responses for client-side errors

Error 400 - Authentication failed

Gmail

Invalid or revoked refresh token.

Cause: The Google refresh token provided is missing one or more of the following required scopes:

userinfo.email
userinfo.profile
openid

Solution: Generate a new Google refresh token that includes all of the required scopes.

Error 400 - Bad request

The browser (or proxy) sent a request that this server could not understand.

Cause: The request was malformed, or it contained an invalid parameter. The most common issue is invalid JSON.

Solution: Ensure your API payload is in a valid JSON format. Make sure all quotes are properly escaped in the code.

Error 400 - Redirect URI is not HTTPS or localhost

Cause: Your project's redirect URI doesn't use the HTTPS protocol, or — if the URI directs to a localhost server — you didn't include http://.

Solution:

For a public URI, add https://.
For a localhost URI, add http://.

Error 400

Microsoft

This proposal does not allow direct password entry. Please restart the authentication flow.

Cause: This occurs for one of the following reasons:

The customer is trying to authenticate an account using Basic auth, which requires the OAuth flow.
The customer's application is not set up for the OAuth flow. There's no Azure app configured for their application.

Solution:

Create an Azure app for Microsoft integrations.
Pass force_password=true in a Hosted auth payload, and select Exchange (see the Hosted authentication documentation for more information).
Enter a random email address during the auth process, then select Exchange.

Error 401 - Unauthorized

Could not verify access credentials.

Cause: This often happens when using endpoints that require the client secret to be encoded. Check your credentials:

Solution: Open a terminal and use the $ echo -n "<NYLAS_CLIENT_SECRET>:" | base64 command to encode your client secret.

Error 402 - Sending to at least one recipient failed

Cause: If a recipient's email address contains non-ASCII characters (such as characters with accents or other diacritics), delivery fails to that email address.

⚠️ Nylas is currently unable to send email messages to email addresses that contain non-ASCII characters.

Error 403 - Unauthorized

Cause: The server wasn't able to authenticate with the end user's email provider.

Solution: Re-authenticate the end user's account and try again.
checkout

Error 403 - Gmail API has not been used in project

Gmail

Cause: The Gmail API is disabled.

Solution: Make sure the Gmail API is enabled in your GCP project.

Error 403 - Different email address returned

Microsoft

Cause: Microsoft 365 returned a different email address from the one that started the authentication process.

Solution: When authenticating with OAuth, the email address used to authenticate must remain the same throughout the process. To troubleshoot, check the following things:

Ensure that the end user isn't entering or selecting a different email address on Microsoft 365 than the one they entered in Nylas.
Make sure the end user isn't trying to log into an alias. They must authenticate with the main account.

If the issue persists, ask the end user to log out of all their Microsoft 365 accounts and try again. You can also ask them to try authenticating from an incognito or private browser session.

Error 422 - Mail provider error

Cause: An error occurred while the email provider was sending an email message.

Solution: See the server_error value in Nylas' JSON response for more information.

Error 422 - Sending Error

Message delivery submission failed.

Cause: The end user tried to send an email message using a different email address than the one synced with Nylas (for example, they synced using nylas@example.com, but tried to send the email message from swag@example.com). See Microsoft sending errors for more information.

Solution:

Check the sending name to ensure that the email address used to send the email message is the same as the synced account.
Try sending the email message again with exponential backoff.
Confirm that the Exchange server hasn't quarantined the syncing devices.

Error 429 - Account throttled

Cause: The account is in a throttled state, and the email server has asked Nylas to temporarily stop making requests.

Solution: Wait and try again later.

📝 If you see a "Rate limiting error when fetching email" or "Too many requests sent to provider" error message when using the v2 Get Message endpoint, contact Nylas Support to discuss enabling raw message caching.

Error 429 - Quota exceeded

Cause: The end user has exceeded their email provider's sending quota.

Solution: There's no reliable way to determine the sending limits for each provider. Wait and try again later.

Error 429 - Nylas API rate limit

Cause: You made too may requests to the Nylas APIs too quickly. See the Rate limiting documentation for more information.

Solution: Wait and try again later.

Error 429 - Too many requests

Gmail

The Gmail account has exceeded the usage limit.

Cause:

You might encounter this error for one of the following reasons:

You exceeded the daily request limit for your GCP project.
You exceeded the user rate limit for your GCP project.

Solutions:

Check your quotas in your GCP project, and request additional daily allowances:

Visit the Enabled APIs page of the API library in the API Console, and select an API from the list.
To view and change quota-related settings, select Quotas. To view usage statistics, select Usage. For example, Gmail API has a limit of 15,000 queries per minute per user.

If you need to reduce volume, add an exponential backoff when you retry failed requests. Use randomness with the backoff schedule to avoid a thundering herd effect.

Error 429 - Resource exhausted

Gmail

Resource has been exhausted (e.g. check quota).

Cause:

You are trying to retrieve or modify too much data per second.

This error often occurs when listing all instances of an object when the user has many, for example when making an unlimited GET /v3/grants/<grant_id>/messages request.

Google has a quota limit of 250 per second for each Gmail account. Each type of API request consumes different amounts of your quota. For example, retrieving one Gmail message costs 5 points of your quota, and sending an email costs 100. See the official Google Usage Limits documentation for more details on how Google calculates your API quota.

Solution:

If you hit this limit when fetching objects, reduce your limit size to 20 or lower, and add query parameters to your request to limit the number of results returned. For example, you might add ?limit=20&starred=true to a get email messages request.

If you hit this limit when modifying multiple objects (for example, changing several email messages from unread to read), add at least one second between each request.

If you hit this limit when retrying failed requests, implement an exponential backoff schedule to reduce request volume. Use randomness with the backoff schedule to avoid a thundering herd effect.

Error 429 - Application is over its MailboxConcurrency limit

Cause:

The Microsoft Graph API allows up to four concurrent requests. That means you cannot process more than four Nylas requests at the same time, and Microsoft returns an error if you try.

For more about the Microsoft concurrent request limit, see the official Microsoft throttling limit documentation.

Solution:

To work around this limit, try to spread out your requests, and implement an exponential backoff to reduce request volume. Use randomness with the backoff schedule to avoid a thundering herd effect.

Error 429 - Exchange account throttled

Microsoft

The Exchange account has been throttled or sync has been temporarily paused.

Cause: You might encounter this error for one of the following reasons:

You reached the Nylas API limits.
An end user reached their email provider's sending limit.
The end user hasn't reached the Nylas API limits, but the Exchange server throttled their account to decrease the load on the server. Exchange servers do this independent of the sending process.
- Nylas received a 503 error and the following message: The server encountered an unknown error, the device SHOULD retry later.<85>..
- The Exchange server sends Nylas a header indicating how long to wait before syncing again. While Nylas is waiting to send, you will receive 429 errors for any email messages you try to send. Typically, this lasts for 20 minutes.

For more information, see the following documentation:

Solution:

Try sending the email message again with exponential backoff.
Check your Exchange server settings. If necessary, talk to your administrator about raising the server's throttling limits.