Oracle ERP Cloud Rate Limits Deep Dive: Concurrent Requests, UCM Uploads, ESS Job Limits

TL;DR

• Bottom line: Oracle Fusion Cloud ERP enforces rate limits at three layers — identity domain (request/min), per-API (records/request), and ESS scheduler (concurrent threads) — with FBDI as the only viable path for bulk loads exceeding 500 records.
• Key limit: Identity domain rate limits cap at 150–4,500 requests/min depending on tier; REST API GET returns max 499 records per page; POST capped at 500 records per request.
• Watch out for: REST and SOAP share the same identity domain rate limit pool — a SOAP-heavy integration will consume capacity for REST calls too.
• Best for: Understanding the complete throttling envelope before designing Oracle ERP Cloud integrations involving high-volume data exchange.
• Authentication: OAuth 2.0 with JWT assertion (server-to-server) or SAML federation; basic auth supported but not recommended for production.

System Profile

This card covers Oracle Fusion Cloud ERP (also marketed as Oracle Cloud ERP, part of Oracle Fusion Cloud Applications Suite) across releases 24B and 25A. The rate limits documented here apply to all SaaS-hosted Oracle Fusion Cloud ERP instances including Financials, Procurement, Project Management, and Supply Chain modules. On-premise Oracle E-Business Suite has entirely different limits and is not covered.

API Surfaces & Capabilities

Oracle Fusion Cloud ERP exposes multiple integration surfaces, each with distinct rate limits and optimal use cases. Choosing the wrong surface is the most common integration design mistake.

Rate Limits & Quotas

Per-Request Limits

Rolling / Daily Limits

Oracle Fusion Cloud ERP rate limits are enforced at the identity domain level, not per-application. All REST and SOAP calls from all integrations targeting the same Fusion environment share a single rate limit pool.

ESS (Enterprise Scheduler) Limits

ESS jobs run server-side and are controlled by thread pools and work assignments rather than traditional API rate limits. These limits determine how many scheduled processes can run concurrently.

Authentication

Authentication Gotchas

• All API calls from a single integration user share the same identity domain rate limit bucket — creating multiple integration users does NOT multiply your rate limits. [src1]
• Basic auth tokens consume from the Authentication request rate limit pool on every call, while OAuth tokens only consume during token acquisition/refresh. [src5]
• Session timeout is configurable by the Fusion admin — never hardcode token lifetimes. Implement token refresh logic that responds to 401 responses. [src3]

Constraints

• REST and SOAP APIs share the same identity domain rate limit pool — a SOAP-heavy legacy integration directly reduces available capacity for new REST integrations.
• FBDI is the only supported path for bulk inbound loads exceeding 500 records — REST API POST is hard-limited and will reject larger payloads.
• ESS thread counts in SaaS environments are Oracle-managed — customers cannot arbitrarily increase concurrent scheduled process capacity without engaging Oracle Support.
• UCM upload timeout of 300 seconds means files approaching the 250 MB limit may fail on slower network connections; practical reliable limit is closer to 150 MB.
• Identity domain rate limits are per-minute rolling windows, not daily quotas — sustained high throughput is possible but burst traffic gets throttled immediately.
• Import jobs (FBDI) should not exceed 10 parallel batches — more causes performance degradation across the environment, potentially affecting other users.
• BIP report extractions are ESS jobs — long-running reports consume the same thread pool as scheduled processes and imports.

Integration Pattern Decision Tree

START - Need to integrate with Oracle Fusion Cloud ERP
|-- What's the integration pattern?
|   |-- Real-time (individual records, <1s)
|   |   |-- Data volume < 500 records/operation?
|   |   |   |-- YES -> REST API (JSON, straightforward CRUD)
|   |   |   +-- NO -> NOT supported real-time; switch to batch/FBDI
|   |   +-- Need event notifications?
|   |       |-- YES -> Business Events (outbound) + REST callback
|   |       +-- NO -> REST API polling with hasMore pagination
|   |-- Batch/Bulk (scheduled, high volume)
|   |   |-- Data volume < 500 records?
|   |   |   |-- YES -> REST API POST (simpler, no file overhead)
|   |   |   +-- NO (go down)
|   |   |-- Data volume < 50,000 records?
|   |   |   |-- YES -> FBDI low-volume mode (single file)
|   |   |   +-- NO (go down)
|   |   |-- Data volume < 500,000 records?
|   |   |   |-- YES -> FBDI high-volume mode (single file)
|   |   |   +-- NO -> FBDI with file splitting (max 20 files/job, 10 parallel jobs)
|   |   +-- Need data extraction (outbound)?
|   |       |-- Small dataset -> REST API with pagination
|   |       +-- Large dataset -> BIP report extraction (BI Publisher)
|   |-- Event-driven
|   |   |-- Oracle publishes events?
|   |   |   |-- YES -> Business Events subscription
|   |   |   +-- NO -> BIP report polling or REST polling (scheduled)
|   |   +-- Guaranteed delivery needed?
|   |       |-- YES -> Middleware (OIC) with error handling + retry
|   |       +-- NO -> Direct REST webhook receiver
|   +-- File-based (CSV/XML)
|       +-- FBDI (standard Oracle pattern) -> Upload CSV to UCM -> Submit ESS import job
|-- Which direction?
|   |-- Inbound (writing to ERP) -> REST (<500 records) or FBDI (>500 records)
|   |-- Outbound (reading from ERP) -> REST API (small) or BIP extraction (large)
|   +-- Bidirectional -> Design conflict resolution FIRST; use REST for real-time sync
+-- Error tolerance?
    |-- Zero-loss required -> Middleware (OIC/MuleSoft) + dead letter queue + FBDI error callbacks
    +-- Best-effort acceptable -> Direct REST with exponential backoff retry

Quick Reference

Step-by-Step Integration Guide

1. Authenticate and obtain access token

Obtain an OAuth 2.0 access token using JWT assertion for server-to-server integration. [src3]

# Exchange JWT for access token
curl -X POST "https://{your-idcs-domain}/oauth2/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
  -d "assertion={your-jwt-assertion}" \
  -d "scope=urn:opc:idm:__myscopes__"

Verify: Response contains access_token field with token_type: "Bearer".

2. Query records with pagination (respecting 499-record limit)

Oracle REST API returns a maximum of 499 records per GET request. Use the offset and limit parameters to paginate. [src3]

# First page
curl -X GET "https://{host}/fscmRestApi/resources/v1/invoices?limit=499&offset=0" \
  -H "Authorization: Bearer {access_token}"

# Check response for hasMore: true, then increment offset
curl -X GET "https://{host}/fscmRestApi/resources/v1/invoices?limit=499&offset=499" \
  -H "Authorization: Bearer {access_token}"

Verify: Response JSON contains hasMore: false when all records retrieved.

3. Upload FBDI file to UCM for bulk import

For bulk loads exceeding 500 records, upload a CSV file to UCM via the ERP Integration web service. [src4]

curl -X POST "https://{host}/fscmRestApi/resources/v1/erpintegrations" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "OperationName": "uploadFileToUCM",
    "DocumentContent": "{base64-encoded-zip-file}",
    "DocumentAccount": "fin$/journal$/import$",
    "ContentType": "zip",
    "FileName": "JournalImport.zip"
  }'

Verify: Response returns DocumentId confirming successful upload.

4. Submit ESS import job and monitor status

After uploading the FBDI file, submit an ESS scheduled process to execute the import. [src7]

# Submit import job
curl -X POST "https://{host}/fscmRestApi/resources/v1/erpintegrations" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "OperationName": "submitESSJobRequest",
    "JobPackageName": "/oracle/apps/ess/financials/generalLedger/programs/",
    "JobDefName": "JournalImportLauncher",
    "ESSParameters": "300000004976094,1,#NULL"
  }'

# Monitor job status
curl -X GET "https://{host}/fscmRestApi/resources/v1/erpintegrations?finder=ESSJobStatusRF;requestId={job_id}" \
  -H "Authorization: Bearer {access_token}"

Verify: Response RequestStatus transitions from RUNNING to SUCCEEDED.

5. Implement rate limit handling with exponential backoff

When you hit the identity domain rate limit, Oracle returns HTTP 429. Implement exponential backoff starting at 2 seconds. [src1, src5]

import time
import requests

def call_oracle_api(url, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 429:
            wait = min(2 ** attempt, 60)  # max 60s
            time.sleep(wait)
            continue
        elif response.status_code == 503:
            wait = min(2 ** (attempt + 1), 120)
            time.sleep(wait)
            continue
        return response
    raise Exception("Max retries exceeded for Oracle API")

Verify: Function returns valid response without 429 errors after retry sequence.

Code Examples

Python: Paginated data extraction with rate limit handling

# Input:  Oracle Fusion REST API endpoint, OAuth token
# Output: Complete list of all matching records across all pages

import requests
import time

def extract_all_records(base_url, endpoint, token, query_params=None):
    headers = {"Authorization": f"Bearer {token}",
               "Content-Type": "application/json"}
    all_records = []
    offset = 0
    limit = 499  # Oracle max per page
    has_more = True

    while has_more:
        url = f"{base_url}/fscmRestApi/resources/v1/{endpoint}"
        params = {"offset": offset, "limit": limit}
        if query_params:
            params.update(query_params)

        for attempt in range(5):
            resp = requests.get(url, headers=headers, params=params)
            if resp.status_code == 429:
                time.sleep(min(2 ** attempt, 60))
                continue
            resp.raise_for_status()
            break

        data = resp.json()
        items = data.get("items", [])
        all_records.extend(items)
        has_more = data.get("hasMore", False)
        offset += limit

    return all_records

JavaScript/Node.js: FBDI file upload with retry

// Input:  Base64-encoded zip file, Oracle REST endpoint, OAuth token
// Output: UCM Document ID confirming successful upload

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

async function uploadFBDI(host, token, fileContent, fileName, docAccount) {
  const url = `${host}/fscmRestApi/resources/v1/erpintegrations`;
  const payload = {
    OperationName: 'uploadFileToUCM',
    DocumentContent: fileContent, // base64 encoded
    DocumentAccount: docAccount,
    ContentType: 'zip',
    FileName: fileName
  };

  for (let attempt = 0; attempt < 5; attempt++) {
    try {
      const resp = await axios.post(url, payload, {
        headers: {
          'Authorization': `Bearer ${token}`,
          'Content-Type': 'application/json'
        },
        timeout: 300000 // 300s to match UCM timeout
      });
      return resp.data.DocumentId;
    } catch (err) {
      if (err.response?.status === 429 || err.response?.status === 503) {
        await new Promise(r => setTimeout(r, Math.min(2 ** attempt * 1000, 60000)));
        continue;
      }
      throw err;
    }
  }
  throw new Error('FBDI upload failed after 5 retries');
}

cURL: Check ESS job status

# Input:  Oracle host, Bearer token, ESS job request ID
# Output: Job status (RUNNING, SUCCEEDED, ERROR, WARNING)

curl -s -X GET \
  "https://{host}/fscmRestApi/resources/v1/erpintegrations?finder=ESSJobStatusRF;requestId={REQUEST_ID}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" | jq '.items[0].RequestStatus'

Data Mapping

Rate Limit Tiers by Identity Domain Type

Data Type Gotchas

• Oracle Fusion dates use ISO 8601 format but the timezone reflects the user's profile timezone, not UTC — always convert to UTC before storing or comparing across systems. [src3]
• Currency amounts in Oracle Fusion use the currency code from the ledger or business unit — multi-currency transactions require explicit conversion rate lookup via the Daily Rates REST resource. [src3]
• FBDI CSV files must use UTF-8 encoding without BOM — files with BOM characters cause silent import failures with no error in the ESS job log. [src6]
• Oracle REST API LOV (List of Values) fields return internal codes, not display labels — map using the LOV REST endpoint or maintain a local lookup table. [src3]

Error Handling & Failure Points

Common Error Codes

Failure Points in Production

• FBDI upload succeeds but import job fails silently: The UCM upload returns success (DocumentId) but the subsequent ESS import job errors without clear messaging. Fix: Always poll ESS job status after submission; parse the job output/log file for detailed error rows. [src4, src6]
• Rate limit exhaustion from token refresh storms: Multiple integration processes refreshing OAuth tokens simultaneously consume the Authentication rate limit bucket. Fix: Cache tokens centrally with TTL slightly shorter than expiration; use a single token service for all integrations. [src1, src5]
• UCM upload timeout on large files: Files approaching 250 MB frequently timeout at the 300-second boundary. Fix: Keep FBDI files under 150 MB; compress CSV into zip before upload; split large imports into multiple files. [src4]
• ESS thread starvation from long-running reports: BIP report extractions run as ESS jobs and can consume all available threads. Fix: Schedule BIP extractions in off-peak workshifts; monitor thread utilization via Scheduled Processes UI. [src7]
• Concurrent FBDI imports cause data corruption: Running more than 10 parallel import jobs for the same object type can cause interface table contention. Fix: Limit parallel imports to 10 maximum; serialize imports for the same object; purge interface tables between runs. [src4]
• SOAP and REST competing for rate limit budget: Legacy SOAP integrations consume from the same identity domain pool. Fix: Audit all integrations sharing the identity domain; migrate SOAP to REST where possible; implement coordinated rate limiting across all clients. [src1]

Anti-Patterns

Wrong: Polling REST API in a tight loop for bulk extraction

# BAD - Hammering API without backoff, will hit 429 within seconds
while True:
    response = requests.get(f"{base}/invoices?offset={offset}")
    process(response.json())
    offset += 499

Correct: Paginated extraction with rate-aware throttling

# GOOD - Respects rate limits, handles 429, uses appropriate delays
import time
offset = 0
while True:
    resp = requests.get(f"{base}/invoices?offset={offset}&limit=499",
                        headers=headers)
    if resp.status_code == 429:
        time.sleep(float(resp.headers.get('Retry-After', 5)))
        continue
    data = resp.json()
    process(data['items'])
    if not data.get('hasMore'):
        break
    offset += 499
    time.sleep(0.5)  # voluntary throttle: ~120 req/min

Wrong: Using REST API POST for bulk data loads

// BAD - REST POST limited to 500 records; 10,000 records = 20 serial calls
for (const batch of chunk(records, 500)) {
    await axios.post(`${base}/journals`, { items: batch });
}

Correct: Use FBDI for bulk loads, REST only for small batches

// GOOD - FBDI handles 500K records per file; single upload + ESS job
const csv = generateCSV(records); // all 10,000 records
const zip = await compressToZip(csv);
const base64 = zip.toString('base64');
const docId = await uploadFBDI(host, token, base64, 'import.zip', account);
const jobId = await submitESSJob(host, token, docId);
await pollJobStatus(host, token, jobId);

Wrong: Creating separate integration users to bypass rate limits

BAD - Rate limits are per identity domain, NOT per user
Creating 5 integration users does not give you 5x the rate limit.
All users in the same identity domain share the same pool.

Correct: Optimize request efficiency within the rate limit budget

GOOD - Maximize value per request:
1. Use query filters (q parameter) to reduce result set size
2. Use fields parameter to request only needed attributes
3. Cache reference data (LOVs, lookups) locally
4. Batch related operations into composite requests (max 50)
5. Schedule bulk operations via FBDI during off-peak hours

Common Pitfalls

• Confusing OCI API limits with Fusion Cloud ERP limits: OCI infrastructure APIs have separate rate limiting from Fusion Cloud application APIs. Fix: Consult OCI service limits documentation separately from Fusion Cloud REST API documentation. [src1]
• Not monitoring rate limit consumption across integrations: With multiple integrations sharing one identity domain, no single team sees the full picture. Fix: Implement centralized API call logging with timestamps; aggregate across all integration clients; set alerts at 70% of rate limit threshold. [src1, src5]
• Running FBDI imports during peak business hours: Large FBDI imports consume ESS threads and can slow down the entire Fusion environment. Fix: Schedule FBDI imports outside business hours; coordinate with Oracle maintenance windows. [src4, src7]
• Ignoring FBDI interface table cleanup: Processed records remain in interface tables indefinitely, slowing subsequent imports. Fix: Run purge jobs after every import cycle; automate purge as the final step in every FBDI integration flow. [src6]
• Assuming sandbox and production have identical limits: Sandbox environments may have lower rate limits and different ESS thread allocations. Fix: Load-test in sandbox but validate rate limit assumptions in production with controlled rollout. [src1]
• Hardcoding API version in integration endpoints: Oracle Fusion releases quarterly; endpoint paths may change. Fix: Use version-agnostic base URLs where available; pin to a specific release version and update during quarterly testing cycles. [src3]

Diagnostic Commands

# Test authentication (obtain token)
curl -s -X POST "https://{idcs-domain}/oauth2/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=urn:opc:idm:__myscopes__" \
  -u "{client_id}:{client_secret}" | jq '.access_token'

# Test REST API connectivity
curl -s -o /dev/null -w "%{http_code}" -X GET \
  "https://{host}/fscmRestApi/resources/v1/" \
  -H "Authorization: Bearer {token}"

# Check ESS scheduled process status
curl -s -X GET \
  "https://{host}/fscmRestApi/resources/v1/erpintegrations?finder=ESSJobStatusRF;requestId={JOB_ID}" \
  -H "Authorization: Bearer {token}" | jq '.items[0] | {Status: .RequestStatus, StartTime: .StartTime, EndTime: .EndTime}'

# List recent ESS jobs (last 20)
curl -s -X GET \
  "https://{host}/fscmRestApi/resources/v1/scheduledProcesses?limit=20&orderBy=SubmittedDT:desc" \
  -H "Authorization: Bearer {token}" | jq '.items[] | {id: .RequestId, name: .Name, status: .Status}'

# Verify object accessibility (describe endpoint)
curl -s -X GET \
  "https://{host}/fscmRestApi/resources/v1/{resource}/describe" \
  -H "Authorization: Bearer {token}" | jq '.Resources[0].attributes | length'

Version History & Compatibility

Deprecation Policy

Oracle Fusion Cloud ERP follows a quarterly release cadence with no formal API version numbering. REST endpoints are release-specific; breaking changes are documented in Release Readiness guides published before each quarterly update. Oracle generally provides one quarter advance notice before removing or changing REST API behavior.

When to Use / When Not to Use

Important Caveats

• Identity domain rate limits are not published per-customer and may vary based on your specific Oracle contract and service tier — the values in this card represent documented tiers but your actual limits should be confirmed with Oracle Support.
• ESS thread counts in Oracle-managed SaaS environments cannot be directly modified by customers — changes require an Oracle Support Service Request and may be subject to additional charges.
• Rate limits are subject to change with each quarterly release — always verify against the current Release Readiness documentation before production deployment.
• Oracle does not expose rate limit remaining/reset headers in Fusion Cloud REST API responses (unlike OCI APIs) — you must track consumption client-side.
• Sandbox and test environments may have lower rate limits and fewer ESS threads than production — do not assume test performance will translate directly to production.