Client error responses: 400–499
Nylas returns 400
responses for client-side errors
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.
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.
400 - Redirect URI is not HTTPS or localhost
Cause: Your 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://
.
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.
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.
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.
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.
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.
403 - Different email address returned
Microsoft
Cause: Office 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 Office 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 Office 365 accounts and try again. You can also ask them to try authenticating from an incognito or private browser session.
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.
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 [email protected]
, but tried to send the email message from [email protected]
). See Nylas' Microsoft sending failures documentation 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.
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.
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.
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.
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.
- You exceeded the project rate limit.
Solution:
- Retry any failed requests.
- Check your quotas in your GCP project, and request additional daily allowances.
- Review Google's official Usage limit exceeded documentation.
429
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.
- Nylas received a
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.