Introduction
Default error handling in OIC is a critical capability that Oracle Integration Cloud developers rely on to ensure integrations behave reliably when unexpected failures occur. In any enterprise integration environment, errors are inevitable—network outages, invalid payloads, API failures, authentication issues, or data mismatches can interrupt integration flows.
Oracle Integration Cloud (OIC Gen 3) provides built-in mechanisms to detect, capture, and manage these failures through default error handling. This feature automatically intercepts unhandled exceptions and prevents integrations from failing silently.
From an implementation consultant’s perspective, proper error handling is not just a technical requirement—it is essential for operational stability, monitoring, and maintainability. Many organizations integrate multiple Oracle Fusion applications such as HCM, ERP, and SCM with external systems. When an error occurs during these integrations, administrators must be able to quickly identify the root cause and take corrective action.
This article explains default error handling in OIC, how it works internally, and how Oracle consultants design integrations that gracefully handle errors.
What is Default Error Handling in OIC?
Default error handling in Oracle Integration Cloud refers to the built-in mechanism that automatically catches exceptions when no custom error handling logic exists in an integration flow.
When an error occurs during execution, OIC performs the following actions automatically:
Stops further execution of the integration flow
Captures error details including:
Fault message
Error code
Failed activity
Stack trace
Logs the error in Tracking and Activity Stream
Marks the integration instance as Failed
Generates a fault response if the integration is synchronous
This mechanism ensures that failures are visible, traceable, and diagnosable.
Types of Errors Captured by Default Handling
Error Type Description Connectivity Errors Adapter connection failures Mapping Errors Invalid transformations SOAP Faults Web service failures REST Errors HTTP 4xx / 5xx responses Timeout Errors Long-running service timeouts Runtime Exceptions Invalid payload structures If developers do not implement a Scope Fault Handler, OIC automatically routes errors to the default handler.
Real-World Integration Use Cases
Understanding default error handling in OIC becomes easier when we look at real enterprise scenarios.
Scenario 1 — Employee Creation Failure (Fusion HCM)
An organization integrates Oracle Fusion HCM with a third-party recruitment platform.
Flow:
Recruitment Tool → OIC → Fusion HCM Worker API
During processing, the payload contains:
EmployeeNumber = NULLFusion HCM requires this field, so the API returns a validation error.
Default error handling will:
Stop the integration
Capture the error response
Log the failure in OIC instance tracking
Mark the instance as Failed
Administrators can review the payload and reprocess the transaction.
Scenario 2 — ERP Invoice Integration Failure
A finance system sends invoice data into Oracle Fusion ERP Payables.
During integration:
External System → OIC → ERP Invoice Interface
If the invoice amount is negative or the supplier does not exist, ERP rejects the request.
Default error handling records:
Fault response from ERP
API error message
Failed activity
This enables finance support teams to identify data errors quickly.
Scenario 3 — SCM Inventory Update API Timeout
A warehouse system calls an integration that updates inventory quantities in Oracle Fusion SCM.
If the ERP API takes too long to respond:
The integration times out
OIC generates a timeout exception
Default error handling logs the timeout error so administrators can identify performance issues.
Architecture and Technical Flow
To understand default error handling in OIC, we need to examine the internal execution flow.
OIC Execution Model
When an integration runs:
Integration instance is created
Trigger receives request
Activities execute sequentially
Adapter calls external systems
Responses are mapped and returned
If an exception occurs at any step:
Activity Failure
↓
Scope Fault Handler (if exists)
↓
Global Fault Handler (if exists)
↓
Default Error HandlingDefault Handler Responsibilities
The default handler performs the following actions:
Function Description Error Capture Stores detailed error message Fault Logging Logs the activity where failure occurred Instance Status Marks instance as Failed Monitoring Displays error in Activity Stream Response Handling Returns fault response to caller Prerequisites
Before implementing integrations that rely on default error handling in OIC, the following prerequisites should be in place.
Environment
Oracle Integration Cloud Gen 3 instance
Developer access to integrations
Required Skills
Developers should understand:
OIC integration design
Adapter configuration
Data mapping
Scope and fault handlers
System Access
Ensure the following roles are assigned:
Role Purpose ServiceDeveloper Build integrations ServiceMonitor Monitor errors ServiceAdministrator Manage integrations Step-by-Step Build Process
This section explains how to observe default error handling in OIC during an integration execution.
Step 1 – Create an Integration
Navigate to:
Home → Integrations → Create
Select:
App Driven OrchestrationEnter values:
Field Example Integration Name CreateEmployeeIntegration Identifier create_employee Package HCMIntegrations Click Create.
Step 2 – Configure Trigger
Add a REST Adapter as the trigger.
Configuration:
Field Value Resource /createEmployee Method POST Payload Format JSON Example payload:
{
“FirstName”: “John”,
“LastName”: “Smith”,
“EmployeeNumber”: “”
}Step 3 – Add ERP or HCM Adapter
Add Oracle Fusion HCM Adapter to call worker creation service.
Configuration:
Field Value Operation createWorker Security Policy OAuth Step 4 – Configure Mapping
Map fields:
Source Target FirstName PersonName LastName PersonLastName EmployeeNumber EmployeeNumber Leave EmployeeNumber empty intentionally for testing.
Step 5 – Do NOT Add Fault Handler
Do not add:
Scope Fault Handler
Global Fault Handler
This ensures the integration relies on default error handling in OIC.
Step 6 – Activate Integration
Click:
ActivateThe integration is now ready for testing.
Testing the Technical Component
Now we test how default error handling behaves.
Test Payload
Send request using Postman:
POST /createEmployeePayload:
{
“FirstName”: “John”,
“LastName”: “Smith”,
“EmployeeNumber”: “”
}Expected Result
Fusion HCM API returns validation error.
OIC will:
Stop execution
Capture error message
Mark instance as Failed
Validate Error in OIC
Navigate to:
Home → Monitoring → Integrations → TrackingOpen the failed instance.
You will see:
Field Example Status Failed Fault EmployeeNumber cannot be null Failed Activity HCM Adapter This confirms default error handling captured the failure.
Understanding the Error Details
OIC stores detailed information for troubleshooting.
Error Components
Component Description Fault Message Description of error Error Code Internal code Activity Name Step where error occurred Instance ID Unique integration run Example error:
oracle.cloud.adapter.api.exception
EmployeeNumber is mandatoryThis information helps consultants identify root causes quickly.
Common Errors and Troubleshooting
During real implementations, developers frequently encounter errors handled by the default mechanism.
1. Invalid Mapping
Problem
Data type mismatch during transformation.
Example:
String → IntegerSolution
Validate mapping logic before activation.
2. Adapter Connection Failure
Problem
External API endpoint unavailable.
Example error:
Connection timed outSolution
Check:
Endpoint URL
Network firewall
Credentials
3. Authentication Errors
Problem
Incorrect OAuth credentials.
Example error:
401 UnauthorizedSolution
Verify:
Client ID
Client Secret
Security policy
4. API Schema Changes
External systems sometimes change their API schema.
This causes:
Payload validation errors
Mapping failures
Always re-import metadata when APIs change.
Best Practices for Default Error Handling
Experienced Oracle consultants follow several best practices.
1. Use Custom Fault Handlers for Critical Integrations
Default error handling is useful but limited.
For critical integrations:
Create Scope Fault Handlers
Capture errors in logs
Send email notifications
2. Enable Integration Tracking
Always enable tracking fields such as:
Field Example EmployeeNumber E12345 InvoiceNumber INV-1001 This makes troubleshooting easier.
3. Implement Retry Mechanisms
Transient failures such as network errors should be retried.
Strategies include:
Scheduled integrations
Message queues
Reprocessing scripts
4. Use Business Identifiers
Business identifiers allow support teams to identify failed transactions quickly.
Example:
OrderNumber
EmployeeID
SupplierInvoiceNumber5. Log Errors for External Monitoring
Many organizations integrate OIC logs with:
OCI Logging
Splunk
ServiceNow
This improves enterprise monitoring.
Summary
Default error handling in OIC provides an automatic safety net for integration failures. When no custom fault handling logic is implemented, Oracle Integration Cloud captures exceptions, logs detailed information, and marks integration instances as failed.
For Oracle consultants, understanding this mechanism is essential because it helps maintain reliable integrations across Oracle Fusion applications such as HCM, ERP, and SCM.
While the default mechanism is helpful for basic error visibility, real enterprise integrations typically implement custom fault handlers, logging strategies, and retry frameworks to ensure high reliability.
Properly designing error handling strategies improves:
Integration stability
Troubleshooting efficiency
Operational monitoring
For deeper technical details, refer to the official Oracle documentation:
https://docs.oracle.com/en/cloud/saas/index.htmlFAQ
1. What is default error handling in OIC?
Default error handling in OIC is the automatic mechanism that captures integration failures when no custom fault handlers are defined. It logs the error, stops execution, and marks the integration instance as failed.
2. When should developers use custom fault handlers instead of default error handling?
Custom fault handlers should be used when integrations require:
Retry logic
Notifications
Custom logging
Error recovery workflows
Default error handling is suitable for basic monitoring.
3. Where can administrators view errors generated by default error handling?
Errors can be viewed in:
Home → Monitoring → Integrations → TrackingAdministrators can open failed instances to view detailed fault messages and activity logs.