Nylas returns 400 responses for client-side errors
Error 400 - Authentication failed
Section titled “Error 400 - Authentication failed”Invalid or revoked refresh token.
Cause: The Google refresh token provided is missing one or more of the following required scopes:
userinfo.emailuserinfo.profileopenid
Solution: Generate a new Google refresh token that includes all of the required scopes.
Error 400 - Bad request
Section titled “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
Section titled “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 402 - Sending to at least one recipient failed
Section titled “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.
Error 403 - Unauthorized
Section titled “Error 403 - Unauthorized”Cause: The server wasn’t able to authenticate with the user’s email provider.
Solution: Re-authenticate the user’s account and try again. checkout
Error 403 - Gmail API has not been used in project
Section titled “Error 403 - Gmail API has not been used in project”Cause: The Gmail API is disabled.
Solution: Make sure the Gmail API is enabled in your Google Cloud project.
Error 403 - Different email address returned
Section titled “Error 403 - Different email address returned”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 user isn’t entering or selecting a different email address on Microsoft 365 than the one they entered in Nylas.
- Make sure the user isn’t trying to log into an alias. They must authenticate with the main account.
If the issue persists, ask the 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 406 - Not Acceptable
Section titled “Error 406 - Not Acceptable”The requested resource cannot generate content matching the request’s
Acceptheaders.
Cause: The request’s content-negotiation headers (Accept, and sometimes Accept-Encoding or Accept-Charset) ask for a response format the Nylas API can’t produce. Because the Nylas APIs return JSON, this usually means the Accept header is set to a value that excludes application/json.
Solution: Set the Accept header to application/json (or omit it to use the default), then retry the request.
Error 422 - Mail provider error
Section titled “Error 422 - Mail provider error”Cause: An error occurred while the email provider was sending a message.
Solution: See the server_error value in Nylas’ JSON response for more information.
Error 422 - Sending Error
Section titled “Error 422 - Sending Error”Message delivery submission failed.
Cause: The user tried to send a message using a different email address than the one synced with Nylas (for example, they synced using [email protected], but tried to send the message from [email protected]). See Microsoft sending errors for more information.
Solution:
- Check the sending name to ensure that the email address used to send the message is the same as the synced account.
- Try sending the message again with exponential backoff.
- Confirm that the Exchange server hasn’t quarantined the syncing devices.
429 rate limit errors by provider
Section titled “429 rate limit errors by provider”When a provider throttles a read request, the API returns a 429 with error.type set to rate_limit_error, a message that tells you which kind of limit you hit, and the provider’s own error in provider_error. If the provider says how long to wait, the response includes a Retry-After header with that number of seconds, rounded up.
The table below covers reads from the Email, Calendar, and Contacts APIs across 7 provider types. Send endpoints can return different messages. Each error links to its full entry on this page, which shows the exact message text and how to fix it.
| Provider | When you see it | Error message | Retry-After header |
|---|---|---|---|
| Microsoft Graph | Graph reports an application-level limit, such as MailboxConcurrency or IncomingBytes | Microsoft rate-limited on application level | Included if Microsoft sends one |
| Microsoft Graph | Any other Graph 429 | Too many requests | Included if Microsoft sends one |
| Google reports that its quota is exhausted | Resource exhausted | Included if Google sends one | |
Any other Google 429, or a Google 403 rate-limit error | Too many requests | Included if Google sends one | |
| Exchange (EWS) | The Exchange server throttles the request | Too many requests | Included if the server sends one |
| iCloud Calendar | iCloud throttles a CalDAV request | Too many requests | Included if iCloud sends one |
| Zoom | Zoom throttles the request | Too many requests | Included if Zoom sends one |
| iCloud Contacts and other CardDAV | The contacts provider throttles the request | Contact provider rate limited | Included if the provider sends one |
| IMAP | The IMAP server throttles the connection | IMAP rate limit hit | Never included |
Wait the number of seconds in Retry-After when it’s present. When it’s missing, retry with a randomized exponential backoff schedule. How to handle rate limit errors has retry examples.
Error 429 - Account throttled
Section titled “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.
Error 429 - Quota exceeded
Section titled “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
Section titled “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
Section titled “Error 429 - Too many requests”Too many requests. If you see this error when fetching objects, set your limit=20 or lower. See
http://nyl.as/429-tmr.
Cause: The provider throttled the request. This is the general rate-limit response for Google, Microsoft Graph, Exchange (EWS), iCloud Calendar, and Zoom grants. The provider_error field contains the provider’s own error, if it returned one. If the provider said how long to wait, the Retry-After header gives that number of seconds, rounded up.
Google sometimes reports a rate limit as a 403 instead of a 429, with the reason rateLimitExceeded or userRateLimitExceeded, or a message such as Quota exceeded or Calendar usage limits exceeded. The API returns these as 429, so you only need to handle one status code. See Google’s error guides for the Gmail API and the Calendar API.
For Google grants, the most common reasons are:
- You exceeded the daily request limit for your Google Cloud project.
- You exceeded the user rate limit for your Google Cloud project.
See Provider rate limits for each provider’s published limits.
Solution:
- Wait the number of seconds in the
Retry-Afterheader before you retry. If the header is missing, retry with a randomized exponential backoff schedule to avoid a thundering herd effect. - If you hit this limit when fetching objects, reduce your
limitto 20 or lower and add query parameters that narrow the results. - For Google grants, check your quotas in your Google Cloud project and request extra daily use allowances if you need them. In the Google API Console, open the Enabled APIs page, select an API, and click Quotas.
Error 429 - Resource exhausted
Section titled “Error 429 - Resource exhausted”Resource exhausted. If you see this error when fetching objects, set your limit=20 or lower. See
http://nyl.as/429-re.
The provider_error field contains Google’s own message: Resource has been exhausted (e.g. check quota).
Cause: You’re trying to fetch or modify too much data too quickly. 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).
For Cloud projects created on or after May 1, 2026, Google limits each user to 6,000 quota units per minute. Projects that used the Gmail API between November 2025 and April 2026 keep their previously set quotas (Gmail usage limits). Each type of API request uses a different amount of your quota: retrieving one Gmail message costs 20 units, listing messages costs 5, and sending an email costs 100.
Solution:
- If you hit this limit when fetching objects, reduce your
limitto 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=trueto 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
Section titled “Error 429 - Application is over its MailboxConcurrency limit”Cause: Microsoft Graph allows up to 4 concurrent requests for each app ID and mailbox combination. Other traffic under the same app ID, including sync, uses the same 4 slots. A Send Message request makes several Graph calls, so 2 or 3 parallel requests to the same grant can fill all 4. Microsoft counts requests in flight, not requests per minute, which is why this error appears even at low send volumes. For more information, see Microsoft’s official Outlook service limits documentation.
Solution: Send to each grant one request at a time, and add 2 to 5 seconds between consecutive sends on the same grant when messages include attachments. Before you retry, wait the number of seconds in the Retry-After header if the response has it. Otherwise, use a randomized exponential backoff schedule to avoid a thundering herd effect. On read requests, this limit returns the Microsoft rate-limited on application level error instead, with Microsoft’s message in provider_error. See Microsoft Graph rate limits for Outlook mail for the full explanation and per-grant queue examples.
Error 429 - Microsoft rate-limited on application level
Section titled “Error 429 - Microsoft rate-limited on application level”Microsoft rate-limited on application level. Please read provider error message in this response for more details.
Cause: Microsoft Graph returned an ApplicationThrottled error. Graph uses this code when an app goes over one of Graph’s Outlook service limits, which apply to each app ID and mailbox combination. Microsoft’s text, in provider_error.error.message, names the limit. For example, Application is over its MailboxConcurrency limit. means 4 requests were already in flight against the mailbox when another arrived, and Application is over its IncomingBytes limit. points to upload volume. See Microsoft’s Outlook service limits documentation.
Solution: Wait the number of seconds in the Retry-After header if it’s present, then retry. If it’s missing, use a randomized exponential backoff schedule. To stop the error recurring, run fewer requests in parallel against the same grant, and spread large attachment uploads over time. See Microsoft Graph rate limits for Outlook mail for per-grant queue examples.
Error 429 - IMAP rate limit hit
Section titled “Error 429 - IMAP rate limit hit”IMAP rate limit hit.
Cause: The IMAP server throttled the connection. IMAP servers don’t say how long to wait, so this response has no Retry-After header. Not all IMAP providers publish their limits.
Solution: Retry with a randomized exponential backoff schedule, and reduce how many requests you run in parallel against the grant. If the error persists, check the limits with the user’s email provider.
Error 429 - Contact provider rate limited
Section titled “Error 429 - Contact provider rate limited”The contact provider rate limited this request. Please retry later.
Cause: A CardDAV contacts provider, such as iCloud Contacts, throttled the request.
Solution: Wait the number of seconds in the Retry-After header if it’s present, then retry. If it’s missing, retry with a randomized exponential backoff schedule.
Error 429 - Exchange account throttled
Section titled “Error 429 - Exchange account throttled”The Exchange account has been throttled or sync has been temporarily paused.
Cause: The Exchange server throttled the account to reduce load, or the user reached their provider’s sending limit. Exchange decides how long the throttle lasts, and the account’s requests keep returning 429 until it ends. The server’s administrator sets its throttling policy.
Solution:
- Wait the number of seconds in the
Retry-Afterheader if the response has it. Otherwise, retry with exponential backoff, and randomize the 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.