Microsoft Graph throttling guidance

• 12/5/2020
• 20 minutes to read
• • d
  • e
  • b
  • l
  • r
  • +11

Throttling limits the number of concurrent calls to a service to prevent overuse of resources. Microsoft Graph is designed to handle a high volume of requests. If an overwhelming number of requests occurs, throttling helps maintain optimal performance and reliability of the Microsoft Graph service.

Throttling limits vary based on the scenario. For example, if you are performing a large volume of writes, the possibility for throttling is higher than if you are only performing reads.

What happens when throttling occurs?

When a throttling threshold is exceeded, Microsoft Graph limits any further requests from that client for a period of time. When throttling occurs, Microsoft Graph returns HTTP status code 429 (Too many requests), and the requests fail. A suggested wait time is returned in the response header of the failed request. Throttling behavior can depend on the type and number of requests. For example, if you have a high volume of requests, all requests types are throttled. Threshold limits vary based on the request type. Therefore, you could encounter a scenario where writes are throttled but reads are still permitted.

Common throttling scenarios

The most common causes of throttling of clients include:

• A large number of requests across all applications in a tenant.
• A large number of requests from a particular application across all tenants.

Sample response

Whenever the throttling threshold is exceeded, Microsoft Graph responds with a response similar to this one.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 2.128

{
  "error": {
    "code": "TooManyRequests",
    "innerError": {
      "code": "429",
      "date": "2020-08-18T12:51:51",
      "message": "Please retry after",
      "request-id": "94fb3b52-452a-4535-a601-69e0a90e3aa2",
      "status": "429"
    },
    "message": "Please retry again later."
  }
}

Best practices to handle throttling

The following are best practices for handling throttling:

• Reduce the number of operations per request.
• Reduce the frequency of calls.
• Avoid immediate retries, because all requests accrue against your usage limits.

When you implement error handling, use the HTTP error code 429 to detect throttling. The failed response includes the Retry-After response header. Backing off requests using the Retry-After delay is the fastest way to recover from throttling because Microsoft Graph continues to log resource usage while a client is being throttled.

1. Wait the number of seconds specified in the Retry-After header.
2. Retry the request.
3. If the request fails again with a 429 error code, you are still being throttled. Continue to use the recommended Retry-After delay and retry the request until it succeeds.

All the resources and APIs described in the Service-specific limits section provide a Retry-After header except when noted.

For a broader discussion of throttling in the Microsoft Cloud, see Throttling pattern.

Best practices to avoid throttling

Programming patterns like continuously polling a resource to check for updates and regularly scanning resource collections to check for new or deleted resources are more likely to lead to applications being throttled and degrade overall performances. You should instead leverage change tracking and change notifications when available.

Throttling and batching

JSON batching allows you to optimize your application by combining multiple requests into a single JSON object. Requests in a batch are evaluated individually against throttling limits and if any request exceeds the limits, it fails with a status of 429 and an error similar to the one provided above. The batch itself fails with a status code of 424 (Failed Dependency). It is possible for multiple requests to be throttled in a single batch. You should retry each failed request from the batch using the value provided in the retry-after response header from the JSON content. You may retry all the failed requests in a new batch after the longest retry-after value.

If SDKs retry throttled requests automatically when they are not batched, throttled requests that were part of a batch are not retried automatically.

Service-specific limits

Microsoft Graph allows you to access data in multiple services, such as Outlook or Azure Active Directory. These services impose their own throttling limits that affect applications that use Microsoft Graph to access them.

Any request can be evaluated against multiple limits, depending on the scope of the limit (per app across all tenants, per tenant for all apps, per app per tenant, and so on), the request type (GET, POST, PATCH, and so on), and other factors. The first limit to be reached triggers throttling behavior. In addition to the service specific-limits described in the section, the following global limits apply:

Note: In this section, the term tenant refers to the Microsoft 365 organization where the application is installed. This tenant can be the same as the the one where the application was created, in the case of a single tenant application, or it can be different, in the case of a multi-tenant application.

Outlook service limits

Outlook service limits are evaluated for each app ID and mailbox combination. In other words, the limits described apply to a specific app accessing a specific mailbox (user or group). If an application exceeds the limit in one mailbox, it does not affect the ability to access another mailbox. The following limits apply to the public cloud as well as national cloud deployments.

Outlook service resources

The following resources are provided by the Outlook service.

Search API resources (preview)

• External item (Microsoft Search)

Profile API resources

• Photo

Calendar API resources

• event
• eventMessage
• calendar
• calendarGroup
• outlookCategory
• attachment
• place (preview)

Mail API resources

• message
• mailFolder
• mailSearchFolder
• messageRule
• outlookCategory
• attachment

Personal contacts API resources

• contact
• contactFolder
• outlookCategory

Social and workplace intelligence resources

• person

To-do tasks API (preview) resources

• outlookTask
• outlookTaskFolder
• outlookTaskGroup
• outlookCategory
• attachment

Cloud communication service limits

OneNote service limits

The preceding limits apply to the following resources:
onenote, notebook, sectionGroup, onenoteSection, onenotePage, onenoteResource, onenoteOperation

You can find additional information about best practices in OneNote API throttling and how to avoid it.

Note: The resources listed above do not return a Retry-After header on 429 Too Many Requests responses.

Project Rome service limits

The preceding limits apply to the following resources:
activityHistoryItem, userActivity

Microsoft Teams service limits

Limits are expressed as requests per second (rps).

A maximum of 4 requests per second per app can be issued on a given team or channel. A maximum of 3000 messages per app per day can be sent to a given channel.

See also Microsoft Teams limits and polling requirements.

The preceding limits apply to the following resources:
aadUserConversationMember, appCatalogs, changeTrackedEntity, channel, chatMessage, chatMessageHostedContent, conversationMember, offerShiftRequest, openShift, openShiftChangeRequest, schedule, scheduleChangeRequest, schedulingGroup, shift, shiftPreferences, swapShiftsChangeRequest, team, teamsApp, teamsAppDefinition, teamsAppInstallation, teamsAsyncOperation, teamsTab, teamsTemplate, teamwork, timeOff, timeOffReason, timeOffRequest, userSettings, workforceIntegration.

Identity and access service limits

These service limits apply to the following entities:

• Directory object
• Extension property
• Administrative unit
• Application
• Application role assignment
• Certificate based auth configuration
• Organizational contact
• Device
• Directory object partner reference
• Directory role
• Directory role template
• Domain
• Domain dns record
• Domain dns cname record
• Domain dns mx record
• Domain dns srv record
• Domain dns txt record
• Domain dns unavailable record
• Endpoint
• Extension property
• License details
• Group
• Activity based timeout policy
• Claims mapping policy
• Home realm discovery policy
• Token issuance policy
• Token lifetime policy
• Policy base
• Sts policy
• Contract
• Service principal
• Subscribed sku
• OAuth2 permission grant
• Organization
• User
• Group setting
• Group setting template

Pattern

Throttling is based on a token bucket algorithm, which works by adding individual costs of requests. The sum of request costs is then compared against pre-determined limits. Only the requests exceeding the limits will be throttled. If any of the limits are exceeded, the response will be 429 Too Many Requests. It is possible to receive 429 Too Many Requests responses even when the following limits are not reached, in situations when the services are under an important load or based on data volume for a specific tenant. The following table lists existing limits.

Note: The application + tenant pair limit varies based on the number of users in the tenant requests are run against. The tenant sizes are defined as follows: S - under 50 users, M - between 50 and 500 users, and L - above 500 users.

The following table lists base request costs. Any requests not listed have a base cost of 1.

Other factors that affect a request cost:

• Using $select decreases cost by 1
• Using $expand increases cost by 1
• Using $top with a value of less than 20 decreases cost by 1

Note: A request cost can never be lower than 1. Any request cost that applies to a request path starting with me/ also applies to equivalent requests starting with users/{id | userPrincipalName}/.

Additional headers

Request headers

• x-ms-throttle-priority - If the header doesn't exist or is set to any other value, it indicates a normal request. We recommend setting priority to high only for the requests initiated by the user. The values of this header can be the following:
  • Low - Indicates the request is low priority. Throttling this request doesn't cause user-visible failures.
  • Normal - Default if no value is provided. Indicates that the request is default priority.
  • High - Indicates that the request is high priority. Throttling this request causes user-visible failures.

Note: Should requests be throttled, low priority requests will be throttled first, normal priority requests second, and high priority requests last. Using the priority request header does not change the limits.

Regular responses requests

• x-ms-resource-unit - Indicates the resource unit used for this request. Values are positive integers.
• x-ms-throttle-limit-percentage - Returned only when the application consumed more than 0.8 of its limit. The value ranges from 0.8 to 1.8 and is a percentage of the use of the limit. The value can be used by the callers to set up an alert and take action.

Throttled responses requests

• x-ms-throttle-scope - eg. Tenant_Application/ReadWrite/9a3d526c-b3c1-4479-ba74-197b5c5751ae/0785ef7c-2d7a-4542-b048-95bcab406e0b. Indicates the scope of throttling with the following format <Scope>/<Limit>/<ApplicationId>/<TenantId|UserId|ResourceId>:
  • Scope: (string, required)
    • Tenant_Application - All requests for a particular tenant for the current application.
    • Tenant - All requests for the current tenant, regardless of the application.
    • Application - All requests for the current application.
  • Limit: (string, requied)
    • Read: Read requests for the scope (GET)
    • Write: Write requests for the scope (POST, PATCH, PUT, DELETE...)
    • ReadWrite: All Requests for the scope (any)
  • ApplicationId (Guid, required)
  • TenantId|UserId|ResourceId: (Guid, required)
• x-ms-throttle-information - Indicates the reason for throttling and can have any value (string). The value is provided for diagnostics and troubleshooting purposes, some examples include:
  • CPULimitExceeded - Throttling is because the limit for cpu allocation is exceeded.
  • WriteLimitExceeded - Throttling is because the write limit is exceeded.
  • ResourceUnitLimitExceeded - Throttling is because the limit for the allocated resource unit is exceeded.

Information protection

The following limits apply to any request on /informationProtection.

The preceding limits apply to the following resources:
threatAssessmentRequest, threatAssessmentResult, mailAssessmentRequest, emailFileAssessmentRequest, fileAssessmentRequest, urlAssessmentRequest.

Identity protection and conditional access service limits

The preceding limits apply to the following resources:
riskDetection, riskyUser, riskyUserHistoryItem, namedLocation, countryNamedLocation, ipNamedLocation, conditionalAccessPolicy.

Note: The resources listed above do not return a Retry-After header on 429 Too Many Requests responses.

Insights service limits

The following limits apply to any request on me/insights or users/{id}/insights.

The preceding limits apply to the following resources:
people, trending, usedinsight, sharedInsight.

Microsoft Graph reports service limits

The following limits apply to any request on /reports.

The preceding limits apply individually to each report API. For example, a request to the Microsoft Teams user activity report API and a request to the Outlook user activity report API within 10 minutes will count as 1 request out of 14 for each API, not 2 requests out of 14 for both.

The preceding limits apply to the report resource.

Invitation manager service limits

The following limits apply to any request on /invitations.

Security detections and incidents service limits

The following limits apply to any request on /security.

Open and schema extensions service limits

The preceding limits apply to the following resources: openTypeExtension, schemaExtension, administrativeUnit, contact, device, event, group, message, organization, post, and user.

Files and lists service limits

Service limits for OneDrive, OneDrive for Business, and SharePoint Online are not available. For more information, see why can't you just tell me the exact throttling limits?.

The preceding information applies to the following resources:
baseItem, baseItemVersion, columnDefinition, columnLink, contentType, drive, driveItem, driveItemVersion, fieldValueSet, itemActivity, itemActivityStat, itemAnalytics, list, listItem, listItemVersion, permission, sharedDriveItem, site, and thumbnailSet.

Tasks and plans service limits

Service limits for Planner are not available.

The preceding information applies to the following resources:
planner, plannerAssignedToTaskBoardTaskFormat, plannerBucket, plannerBucketTaskBoardTaskFormat, plannerGroup, plannerPlan, plannerPlanDetails, plannerProgressTaskBoardTaskFormat, plannerTask, plannerTaskDetails, and plannerUser.

Identity and access data policy operation service limits

The preceding limits apply to the following resources: dataPolicyOperation.

Note: The resources listed above do not return a Retry-After header on 429 Too Many Requests responses.

Education service limits

The preceding limits apply to the following resources:
educationClass, educationOrganization, educationRoot, educationSchool, educationStudent, educationTeacher, educationTerm, educationUser.

Excel service limits

The preceding limits apply to the following resources:
workbook, workbookApplication, workbookChart, workbookChartAreaFormat, workbookChartAxes, workbookChartAxis, workbookChartAxisFormat, workbookChartAxisTitle, workbookChartAxisTitleFormat, workbookChartDataLabelFormat, workbookChartDataLabels, workbookChartFill, workbookChartFont, workbookChartGridlines, workbookChartGridlinesFormat, workbookChartLegend, workbookChartLegendFormat, workbookChartLineFormat, workbookChartPoint, workbookChartPointFormat, workbookChartSeries, workbookChartSeriesFormat, workbookChartTitle, workbookChartTitleFormat, workbookComment, workbookCommentReply, workbookFilter, workbookFormatProtection, workbookFunctionResult, workbookFunctions, workbookNamedItem, workbookOperation, workbookPivotTable, workbookRange, workbookRangeBorder, workbookRangeFill, workbookRangeFont, workbookRangeFormat, workbookRangeSort, workbookRangeView, workbookTable, workbookTableColumn, workbookTableRow, workbookTableSort, workbookWorksheet, workbookWorksheetProtection.

Identity and access audit logs service limits

The preceding limits apply to the following resources:
auditLogRoot, directoryAudit, restrictedSignIn, signIn.

Identity providers service limits

The preceding limits apply to the following resources:
identityContainer, identityProvider.

Intune service limits

Intune applications service limits

The preceding limits apply to the following resources:
iosMobileAppConfiguration, managedDeviceMobileAppConfiguration, managedDeviceMobileAppConfigurationAssignment, managedDeviceMobileAppConfigurationDeviceStatus, managedDeviceMobileAppConfigurationDeviceSummary, managedDeviceMobileAppConfigurationUserStatus, managedDeviceMobileAppConfigurationUserSummary, mobileApp, mobileAppAssignment, mobileAppCategory, mobileAppContent, mobileAppContentFile.

Intune books service limits

The preceding limits apply to the following resources:
deviceInstallState, eBookInstallSummary, iosVppEBook, iosVppEBookAssignment, managedEBook, managedEBookAssignment, userInstallStateSummary.

Intune company terms service limits

The preceding limits apply to the following resources:
termsAndConditions, termsAndConditionsAcceptanceStatus, termsAndConditionsAssignment.

Intune device configuration service limits

The preceding limits apply to the following resources:
deviceComplianceActionItem, deviceComplianceDeviceOverview, deviceComplianceDeviceStatus, deviceCompliancePolicy, deviceCompliancePolicyAssignment, deviceCompliancePolicyDeviceStateSummary, deviceCompliancePolicySettingStateSummary, deviceCompliancePolicyState, deviceComplianceScheduledActionForRule, deviceComplianceSettingState, deviceComplianceUserOverview, deviceComplianceUserStatus, deviceConfiguration, deviceConfigurationAssignment, deviceConfigurationDeviceOverview, deviceConfigurationDeviceStateSummary, deviceConfigurationDeviceStatus, deviceConfigurationState, deviceConfigurationUserOverview, deviceConfigurationUserStatus, deviceManagement, iosUpdateDeviceStatus, settingStateDeviceSummary, softwareUpdateStatusSummary.

Intune device enrollment service limits

The preceding limits apply to the following resources:
complianceManagementPartner, deviceAppManagement, deviceCategory, deviceEnrollmentConfiguration, deviceEnrollmentLimitConfiguration, deviceEnrollmentPlatformRestrictionsConfiguration, deviceEnrollmentWindowsHelloForBusinessConfiguration, deviceManagementExchangeConnector, deviceManagementPartner, enrollmentConfigurationAssignment, mobileThreatDefenseConnector, onPremisesConditionalAccessSettings, vppToken.

Intune devices service limits

The preceding limits apply to the following resources:
applePushNotificationCertificate, detectedApp, managedDevice, managedDeviceOverview.

Intune enrollment service limits

The preceding limits apply to the following resources:
complianceManagementPartner, deviceAppManagement, deviceCategory, deviceEnrollmentConfiguration, deviceEnrollmentLimitConfiguration, deviceEnrollmentPlatformRestrictionsConfiguration, deviceEnrollmentWindowsHelloForBusinessConfiguration, deviceManagementExchangeConnector, deviceManagementPartner, enrollmentConfigurationAssignment, mobileThreatDefenseConnector, onPremisesConditionalAccessSettings, vppToken.

Intune managed applications service limits

The preceding limits apply to the following resources:
managedAppOperation, managedAppPolicy, managedAppPolicyDeploymentSummary, managedAppRegistration, managedAppStatus, managedMobileApp, targetedManagedAppPolicyAssignment, windowsInformationProtectionAppLockerFile.

Intune notifications service limits

The preceding limits apply to the following resources:
localizedNotificationMessage, notificationMessageTemplate.

Intune rbac service limits

The preceding limits apply to the following resources:
resourceOperation, roleAssignment, roleDefinition.

Intune remote assistance service limits

The preceding limits apply to the following resources:
remoteAssistancePartner.

Intune reporting service limits

The preceding limits apply to the following resources:
auditLogRoot, directoryAudit, restrictedSignIn, signIn.

Intune TEM service limits

The preceding limits apply to the following resources:
telecomExpenseManagementPartner.

Intune troubleshooting service limits

The preceding limits apply to the following resources:
deviceManagementTroubleshootingEvent, enrollmentTroubleshootingEvent.

Intune wip service limits

The preceding limits apply to the following resources:
windowsInformationProtectionAppLearningSummary, windowsInformationProtectionNetworkLearningSummary.

Skype service limits

The preceding limits apply to the following resources:
call, cancelMediaProcessingOperation, cloudCommunications, commsOperation, inviteParticipantsOperation, muteParticipantOperation, onlineMeeting, participant, playPromptOperation, recordOperation, subscribeToToneOperation, unmuteParticipantOperation, updateRecordingStatusOperation.

Subscription service limits

The preceding limits apply to the following resources:
subscription.

Assignment service limits

The following limits apply to requests on the assignment service beta API:

The preceding limits apply to the following resources: educationAssignment educationSubmission educationResource