specification: API Commons Rate Limits
specificationVersion: '0.1'
schema: https://raw.githubusercontent.com/api-evangelist/interface-research/main/schema/api-commons.yml#/$defs/RateLimits
provider: Microsoft Word
providerId: microsoft-word
created: '2026-05-04'
# Provenance stamped 2026-08-11: this artifact was written by the API Evangelist
# bulk sweep dated 2026-05-04, not harvested from the provider. See roadmap#35.
method: generated
modified: '2026-05-05'
reconciled: true
tags:
  - Rate Limiting
  - Productivity
  - Documents
  - Microsoft
description: Microsoft Word programmatic surfaces — the Word JavaScript API (Office.js Add-ins) executing
  in-app, and the Microsoft Graph Word / OneDrive endpoints — inherit Microsoft Graph's per-tenant /
  per-app throttling. Graph throttling is dynamic (based on resource consumption) rather than a single
  published per-second number; OneDrive enforces a documented per-user-per-app limit. 429 responses
  carry Retry-After.
sources:
  - https://learn.microsoft.com/en-us/graph/throttling
  - https://learn.microsoft.com/en-us/graph/throttling-limits
  - https://learn.microsoft.com/en-us/office/dev/add-ins/develop/application-specific-api-model
headers:
  retryAfter: Retry-After
  ratelimitLimit: RateLimit-Limit
  ratelimitRemaining: RateLimit-Remaining
  ratelimitReset: RateLimit-Reset
responseCodes:
  throttled: 429
  serviceUnavailable: 503
limits:
  - name: Microsoft Graph (per-app, per-tenant)
    scope: account
    metric: varies
    limit: 'Dynamic; see Microsoft Graph throttling-limits page for service-specific numbers'
  - name: OneDrive / SharePoint (per-app, per-user)
    scope: account
    metric: varies
    limit: '~1,200 / 5,000 requests per minute, varies by endpoint and license tier'
  - name: Word JavaScript API (Office.js Add-ins)
    scope: device
    metric: varies
    limit: 'In-process; bound by host application performance, not metered as a network API'
  - name: Word document protocols (WOPI / IRM)
    scope: account
    metric: varies
    limit: 'Subject to OneDrive / SharePoint throttling for the underlying documents'
policies:
  - name: Honor Retry-After
    description: Microsoft Graph and OneDrive return 429 / 503 with Retry-After. Pause for that many
      seconds, then retry with exponential backoff and jitter.
  - name: Decorate user-agent
    description: Use a meaningful User-Agent / x-anchorMailbox header per Graph guidance to reduce
      throttling impact.
  - name: Use ChangeNotifications, not polling
    description: Subscribe to OneDrive change notifications instead of polling /drive/root/delta to
      avoid hitting per-minute caps.
  - name: Batch with $batch
    description: Use Microsoft Graph $batch endpoints (up to 20 requests) to reduce per-call overhead.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com