Dynamics 365 Web API (OData v4) Capabilities & Rate Limits

TL;DR

• Bottom line: Both D365 F&O and Business Central expose OData v4 endpoints with full CRUD, but they have completely different service protection limits, throttling mechanisms, and API architectures -- treat them as separate integration targets.
• Key limit: F&O allows 6,000 requests per 5-minute sliding window per user per web server, with 52 max concurrent requests; BC allows 5 concurrent OData requests per user with a 6,000/5min rate limit.
• Watch out for: F&O has two layers of service protection -- user-based (optional since 10.0.36) and resource-based (always on). Resource-based limits trigger on aggregate server CPU/memory, not just your user's requests.
• Best for: Real-time CRUD operations on individual records or small batches via OData v4; use Data Management Framework (DMF) for bulk file-based loads >10K records.
• Authentication: OAuth 2.0 via Microsoft Entra ID (Azure AD) -- both Authorization Code flow (user context) and Client Credentials flow (service-to-service / app-only).

System Profile

This card covers the OData v4 Web API surfaces for two distinct Microsoft Dynamics 365 products: Finance & Operations (F&O, also called Finance & Supply Chain Management / F&SCM) and Business Central (BC). While both use OData v4, they have different API architectures, endpoint structures, rate limits, and throttling behaviors. F&O exposes data entities at /data/ endpoints with server-driven paging. BC exposes standard API v2.0 entities at /api/v2.0/ and OData web services at /ODataV4/. This card does not cover the Dataverse Web API, Virtual Entities, or Dual Write. [src1, src2, src3]

API Surfaces & Capabilities

[src1, src2, src3, src6]

Rate Limits & Quotas

F&O: User-Based Service Protection Limits (per user, per app ID, per web server)

Important: As of version 10.0.36, user-based limits are disabled by default and the option to enable them has been removed. Resource-based limits remain mandatory. [src1]

F&O: Resource-Based Limits (environment-wide, always on)

[src1]

F&O: Exempt Services

The following are exempt from OData service protection limits: DIXF/DMF, Recurring Integrations, Power Platform Virtual Tables (when PP integration enabled), F&O Connector, Warehouse Mobile App, Retail Server API, Office Integration, Document Routing Agent. [src1]

BC: Per-User Operational Limits

[src3, src4]

BC: Per-Environment Limits

[src3]

F&O: OData v4 Query Capabilities

[src2]

Authentication

[src1, src2]

Authentication Gotchas

• F&O and BC use different Microsoft Entra ID app registrations -- an app registered for F&O cannot directly access BC APIs. Each requires its own API permissions. [src1, src7]
• F&O throttling key combines user object ID + application client ID. A single service principal shares one 6,000/5min budget for all requests. Distribute across multiple SPs for higher throughput. [src1]
• Client Credentials flow in F&O uses the application's object ID as the "user" for throttling purposes. [src1]
• BC OAuth tokens are scoped to a specific environment (production vs sandbox). Tokens for sandbox cannot access production. [src7]

Constraints

• F&O OData $expand supports first-level only -- nested $expand queries will fail. [src2]
• F&O OData does not support $search, the has operator, or the in operator in $filter. [src2]
• F&O OData does not support array fields in data entities. [src2]
• F&O resource-based service protection limits cannot be disabled and may throttle well-behaved integrations during peak load. [src1]
• BC has a strict 10-minute execution timeout per request with no retry mechanism. [src4]
• BC OData page endpoints will be deprecated in 2027 -- migrate to API v2.0 or custom API pages. [src7]
• BC $batch limited to 100 operations per request. [src3]
• BC SOAP endpoints are being deprecated -- use OData/API for all new integrations. [src3]
• First OData call after F&O AOS restart takes significantly longer due to metadata cache building. [src2]

Integration Pattern Decision Tree

START -- Integrate with Dynamics 365 F&O or Business Central
|-- Which D365 product?
|   |-- Finance & Operations (F&O)
|   |   |-- What volume?
|   |   |   |-- < 1,000 records/day
|   |   |   |   |-- Real-time needed?
|   |   |   |   |   |-- YES -> OData v4 data entities (individual CRUD)
|   |   |   |   |   +-- NO -> OData v4 with scheduled polling
|   |   |   |-- 1,000-100,000 records/day
|   |   |   |   |-- Need atomic transactions?
|   |   |   |   |   |-- YES -> OData $batch with changesets
|   |   |   |   |   +-- NO -> Data Management REST API (package-based)
|   |   |   +-- > 100,000 records/day
|   |   |       +-- Data Management Framework (DMF) package import
|   |   |           (exempt from service protection limits)
|   |   +-- Need event-driven notifications?
|   |       |-- YES -> Business Events + Azure Service Bus / Event Grid
|   |       +-- NO -> OData polling with $filter on ModifiedDateTime
|   +-- Business Central (BC)
|       |-- What volume?
|       |   |-- < 1,000 records/day -> Standard API v2.0 (direct CRUD)
|       |   |-- 1,000-10,000 records/day -> API v2.0 with $batch (max 100 ops)
|       |   +-- > 10,000 records/day -> Distribute across multiple users/SPs
|       +-- Custom business logic needed?
|           |-- YES -> Custom API pages (AL) or OData unbound actions
|           +-- NO -> Standard API v2.0 endpoints (~55 entities)
|-- Which direction?
|   |-- Inbound (writing to D365) -> check concurrent request limits
|   |-- Outbound (reading from D365) -> check page size + execution timeout
|   +-- Bidirectional -> design conflict resolution + use ModifiedDateTime tracking
+-- Error tolerance?
    |-- Zero-loss required -> implement idempotency + Retry-After logic + DLQ
    +-- Best-effort acceptable -> exponential backoff on 429 responses

Quick Reference

F&O Key OData Endpoints

[src2]

BC Key API Endpoints

[src7]

Step-by-Step Integration Guide

1. Register an application in Microsoft Entra ID

Create an app registration in Azure Portal. For F&O, add the Dynamics ERP API permission. For BC, add Dynamics 365 Business Central API permission. [src1, src7]

# Azure CLI: Create app registration
az ad app create \
  --display-name "D365-Integration-App" \
  --sign-in-audience AzureADMyOrg

# Create a client secret
az ad app credential reset --id <app-id> --append

Verify: az ad app show --id <app-id> -> returns app registration details.

2. Obtain an OAuth 2.0 access token

Use Client Credentials flow for server-to-server integration. The scope differs between F&O and BC. [src1, src7]

# F&O: Get access token
curl -X POST "https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token" \
  -d "client_id={app-id}&client_secret={secret}&scope=https://{env}.operations.dynamics.com/.default&grant_type=client_credentials"

# BC: Get access token
curl -X POST "https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token" \
  -d "client_id={app-id}&client_secret={secret}&scope=https://api.businesscentral.dynamics.com/.default&grant_type=client_credentials"

Verify: Response contains access_token field. Decode at jwt.ms to confirm audience and scopes.

3. Query data entities via OData

Use the access token to make authenticated OData requests. [src2, src7]

# F&O: List customers
curl -H "Authorization: Bearer {token}" \
  "https://{env}.operations.dynamics.com/data/CustomersV3?$top=10&cross-company=true"

# BC: List customers
curl -H "Authorization: Bearer {token}" \
  "https://api.businesscentral.dynamics.com/v2.0/{tenant}/{env}/api/v2.0/companies({id})/customers?$top=10"

Verify: Response returns 200 OK with value array containing entity records.

4. Implement rate limit handling with Retry-After

When the service returns 429, read the Retry-After header and wait before retrying. [src1, src5]

import requests, time

def d365_api_call(url, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 200:
            return response.json()
        elif response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 30))
            time.sleep(retry_after)
        elif response.status_code == 503:
            time.sleep(10 * (attempt + 1))
        else:
            response.raise_for_status()
    raise Exception(f"Max retries exceeded for {url}")

Verify: Call succeeds on retry; Retry-After header value should be respected.

Code Examples

Python: Paginated OData query for F&O with cross-company support

# Input:  F&O environment URL, entity name, OAuth token
# Output: All records across pages as a list of dicts

import requests, time

def fetch_all_fo_records(base_url, entity, token, filter_expr=None):
    headers = {"Authorization": f"Bearer {token}", "Accept": "application/json"}
    url = f"{base_url}/data/{entity}?cross-company=true&$count=true"
    if filter_expr:
        url += f"&$filter={filter_expr}"

    all_records = []
    while url:
        response = requests.get(url, headers=headers)
        if response.status_code == 429:
            time.sleep(int(response.headers.get("Retry-After", 30)))
            continue
        response.raise_for_status()
        data = response.json()
        all_records.extend(data.get("value", []))
        url = data.get("@odata.nextLink")  # Server-driven paging
    return all_records

JavaScript/Node.js: BC API v2.0 CRUD with ETag handling

// Input:  BC environment URL, company ID, OAuth token
// Output: Customer records with proper ETag concurrency

const axios = require('axios'); // v1.6+

async function updateBCCustomer(baseUrl, companyId, customerId, data, token) {
  // Step 1: Get current record to obtain ETag
  const current = await axios.get(
    `${baseUrl}/api/v2.0/companies(${companyId})/customers(${customerId})`,
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  const etag = current.data['@odata.etag'];

  // Step 2: Update with If-Match header
  return await axios.patch(
    `${baseUrl}/api/v2.0/companies(${companyId})/customers(${customerId})`,
    data,
    { headers: { 'Authorization': `Bearer ${token}`, 'If-Match': etag } }
  );
}

cURL: F&O $batch request with changeset

# Input:  F&O access token, entity data for batch create
# Output: Batch response with individual operation results

curl -X POST "https://{env}.operations.dynamics.com/data/$batch" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: multipart/mixed; boundary=batch_boundary" \
  -H "OData-Version: 4.0" \
  --data-binary '
--batch_boundary
Content-Type: multipart/mixed; boundary=changeset_boundary

--changeset_boundary
Content-Type: application/http
Content-ID: 1

POST /data/CustomersV3 HTTP/1.1
Content-Type: application/json

{"CustomerAccount":"CUST001","OrganizationName":"Contoso Ltd","dataAreaId":"usmf"}

--changeset_boundary--
--batch_boundary--'

Data Mapping

F&O OData Data Entity Model

[src2]

BC API v2.0 Data Model

[src7]

Data Type Gotchas

• F&O DateTimeOffset fields are always UTC. Client applications must handle timezone conversion. [src2]
• F&O enum fields return integer values -- use $metadata for label mapping. [src2]
• BC requires @odata.etag in If-Match header for every PATCH/DELETE. Omitting returns 412 Precondition Failed. [src7]
• BC systemId (GUID) is the API identifier, distinct from the human-readable number field. [src7]

Error Handling & Failure Points

Common Error Codes

[src1, src3, src7]

Failure Points in Production

• F&O metadata cache cold start: First OData call after AOS restart takes 30-60s. Fix: Enable OData metadata warmup in AOS startup configuration. [src2]
• F&O cross-company performance: Queries with cross-company=true across many legal entities hit execution time limits. Fix: Filter by dataAreaId to target specific companies. [src2]
• BC ETag race conditions: Concurrent updates to the same record fail with 412. Fix: Implement optimistic concurrency retry loop: fetch -> update -> on 412, re-fetch and re-apply. [src7]
• F&O resource-based throttling during month-end: Other workloads consume server resources. Fix: Schedule integrations outside peak hours; use throttling prioritization. [src1]
• BC webhook subscription loss: Subscriptions dropped after 10 consecutive callback errors. Fix: Monitor via GET /api/v2.0/subscriptions; implement renewal logic. [src3]
• F&O $batch partial failures: Requests outside changesets can partially succeed. Fix: Wrap related operations in changesets; implement idempotency checks. [src2]

Anti-Patterns

Wrong: Polling all records to detect changes

# BAD -- Fetches all records every time to find what changed
all_customers = fetch_all_fo_records(base_url, "CustomersV3", token)
# Compare each against local cache... wastes API calls, hits rate limits

Correct: Use $filter on ModifiedDateTime for incremental sync

# GOOD -- Only fetches records modified since last sync
filter_expr = f"ModifiedDateTime gt {last_sync_utc}"
changed = fetch_all_fo_records(base_url, "CustomersV3", token, filter_expr)

Wrong: Single service principal for all F&O traffic

# BAD -- All requests share one user's 6,000/5min budget
sp_token = get_token(client_id="single-app-id", ...)
for batch in all_batches:
    call_api(batch, token=sp_token)  # Hits 429 quickly at scale

Correct: Distribute requests across multiple service principals

# GOOD -- Each SP has its own 6,000/5min budget per web server
sps = [{"client_id": "app-1", ...}, {"client_id": "app-2", ...}]
for i, batch in enumerate(all_batches):
    token = get_token(**sps[i % len(sps)])
    call_api(batch, token=token)  # 2x+ throughput

Wrong: Omitting ETag in BC update operations

// BAD -- Missing If-Match header causes 412 errors
await axios.patch(`${baseUrl}/customers(${id})`, data, {
  headers: { 'Authorization': `Bearer ${token}` }
}); // Returns 412 Precondition Failed

Correct: Always include ETag from the most recent GET

// GOOD -- Fetch current ETag, include in update
const current = await axios.get(`${baseUrl}/customers(${id})`, { headers });
const etag = current.data['@odata.etag'];
await axios.patch(`${baseUrl}/customers(${id})`, data, {
  headers: { ...headers, 'If-Match': etag }
});

Common Pitfalls

• F&O sandbox vs production limits differ: Sandbox environments may have fewer web servers, meaning lower effective capacity. Fix: Load-test in a sandbox matching production web server count. [src1]
• F&O entity key complexity: Many entities have 3-5 field composite keys. Missing any returns cryptic 400. Fix: Check $metadata for entity key fields before building URLs. [src2]
• BC per-user vs per-environment confusion: Per-user limits are actively enforced (since late 2023). Fix: Design for per-user limits; distribute across multiple users/SPs. [src3]
• F&O $expand limitations: Nested $expand silently returns only first level. Fix: Make separate API calls for nested entities. [src2]
• BC OData page deprecation: /ODataV4/ endpoints deprecating 2027. Fix: Migrate to API v2.0 or custom API pages. [src7]
• F&O SaveChangesOptions default: .NET OData client POSTs all fields including unset ones. Fix: Use SaveChangesOptions.PostOnlySetProperties. [src2]

Diagnostic Commands

# F&O: Check OData service availability
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer {token}" \
  "https://{env}.operations.dynamics.com/data/$metadata"
# Expected: 200

# F&O: List all available data entities
curl -s -H "Authorization: Bearer {token}" \
  "https://{env}.operations.dynamics.com/data/"

# F&O: Test simple query
curl -s -H "Authorization: Bearer {token}" \
  "https://{env}.operations.dynamics.com/data/CustomersV3?$top=1&cross-company=true"

# BC: Check API availability
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer {token}" \
  "https://api.businesscentral.dynamics.com/v2.0/{tenant}/{env}/api/v2.0/companies"

# BC: List companies
curl -s -H "Authorization: Bearer {token}" \
  "https://api.businesscentral.dynamics.com/v2.0/{tenant}/{env}/api/v2.0/companies"

# BC: Check webhook subscriptions
curl -s -H "Authorization: Bearer {token}" \
  "https://api.businesscentral.dynamics.com/v2.0/{tenant}/{env}/api/v2.0/subscriptions"

Version History & Compatibility

[src1, src3, src7]

When to Use / When Not to Use

Important Caveats

• F&O service protection limits are per user, per app ID, per web server. Multiple web servers multiply effective capacity, but load balancing is not guaranteed even. [src1]
• User-based limits in F&O are disabled by default since 10.0.36. Resource-based limits are always on and may throttle your integration even when within user-based limits. [src1]
• BC per-user rate of 6,000/5min is strictly enforced since late 2023, unlike the previous per-environment rates. [src3]
• All rate limits are subject to change with each release. Always verify against current Microsoft documentation. [src1, src3]
• F&O on-premises deployments do not have service protection limits. [src1]
• The exemption list for F&O service protection may change -- Microsoft will provide notice before removing exemptions. [src1]