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 user's account has been throttled, and the provider email server has asked Nylas to temporarily stop making requests.

Solution: Wait and try again later. For more information, see Avoiding rate limits in Nylas.

📝 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 user exceeded their provider's sending quota.

Solution: Wait and try again later. See Provider rate limits for more information.

Error 429 - Nylas API rate limit

Cause: You made too many requests to the Nylas APIs too quickly. For more information, see Avoiding rate limits in Nylas.

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.

See Nylas' Google rate limits documentation for more information.

Solution: Check your quotas in your GCP project, and request extra daily use allowances.

In the Google API Console, navigate to the Enabled APIs page and select an API from the list.
Review your project's usage, then click Quotas to view and update quota-related settings.

If you need to reduce your usage volume, use an exponential backoff when you retry failed requests. You should randomize the backoff schedule to avoid a thundering herd effect.

Error 429 - Resource exhausted

Gmail

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

Cause: You're trying to fetch or modify too much data per second. This error often occurs when you're trying to list all instances of an object on an account that has many (for example, when making an unlimited Get all Messages request).

Google has a quota limit of 250 per second for each Gmail account. Each type of API request uses different amounts of your quota (for example, retrieving one Gmail message costs 5 points, while sending an email costs 100). See Google's official Usage limits documentation for more information on how Google calculates your API quota.

Solution:

If you hit this limit when fetching objects, reduce your limit to 20 or lower and add query parameters to your request to limit the number of results Nylas returns. For example, you could add ?limit=20&starred=true to a Get all Messages request to retrieve only the 20 most recent starred messages.
If you hit this limit when modifying multiple objects (for example, changing several messages from unread to read), add at least a one second delay between each request.
If you hit this limit when retrying failed requests, use an exponential backoff schedule to reduce request volume. You should randomize the backoff schedule to avoid a thundering herd effect.

Error 429 - Application is over its MailboxConcurrency limit

Microsoft

Cause: The Microsoft Graph APIs allow up to four concurrent requests. That means you can't process more than four Nylas requests at the same time, and Microsoft returns an error if you try. For more information, see Microsoft's official throttling limits documentation.

Solution: To work around this limit, try to spread out your requests, and use an exponential backoff schedule to reduce request volume. You should randomize 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.
A user reached their email provider's sending limit.
The user hasn't reached the Nylas API limits, but the Exchange server throttled their account to decrease load on the server. Exchange severs do this independent of the sending process.
- Nylas receives a 503 error with 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 messages you try to send. Typically, this lasts for 20 minutes.

For more information, see the following documentation:

Solution:

Try sending the message again with exponential backoff. You should randomize the backoff schedule to avoid a thundering herd effect.
Check your Exchange server settings. If necessary, talk to the server administrator about raising the server's throttling limits.