Introduction
Error handling is one of the most critical aspects of building reliable integrations in Oracle Integration Cloud. In real enterprise integrations, failures are unavoidable. APIs may return errors, downstream applications may be unavailable, data validation can fail, or authentication may expire.
In such situations, integration developers must handle errors gracefully so that business users understand what went wrong and systems can recover appropriately. Oracle Integration Cloud provides several mechanisms to manage failures, including Global Fault Handlers, Scope Fault Handlers, and explicit fault actions.
Among these mechanisms, two powerful actions are:
Throw New Fault
Rethrow Fault
These actions allow developers to control how faults propagate through integrations, determine whether a fault should be modified, wrapped, or simply passed upward.
Understanding when to use Throw New Fault vs Rethrow Fault is essential for designing robust enterprise integrations, especially when working with Fusion ERP, HCM, SCM APIs, REST/SOAP services, and external systems.
This article explains the concept in detail, including real-world scenarios, architecture flow, implementation steps, testing strategies, troubleshooting tips, and best practices.
What is Throw New Fault and Rethrow Fault in OIC?
In Oracle Integration Cloud, fault actions define how an integration responds when an error occurs.
Two important actions available inside fault handlers are:
| Fault Action | Purpose |
|---|---|
| Throw New Fault | Creates a completely new custom fault message |
| Rethrow Fault | Propagates the original fault to the parent scope or global handler |
These actions are typically used inside:
Scope Fault Handler
Global Fault Handler
Both are available in App Driven Orchestration integrations in OIC Gen 3.
Key Idea
| Scenario | Recommended Action |
|---|---|
| Modify the error message | Throw New Fault |
| Pass original fault upward | Rethrow Fault |
Why Fault Propagation Matters in Enterprise Integrations
In real projects, integrations are rarely simple. They typically involve multiple systems such as:
Oracle Fusion Cloud ERP
Oracle Fusion Cloud HCM
Oracle Fusion Cloud SCM
External REST APIs
Legacy databases
Middleware services
When failures occur, developers must decide:
Should the error message be customized for business users?
Should the original technical error be preserved?
Should the fault trigger another integration or notification?
Throw New Fault and Rethrow Fault provide precise control over this behavior.
Real-World Integration Use Cases
Scenario 1 — Custom Error Message for Business Users
A payroll integration sends employee compensation data from OIC to Oracle Fusion HCM.
If salary amount is invalid, the API may return a complex technical error like:
Instead of exposing this technical error, the integration can:
Throw a New Fault
Example message:
This makes the error easier for HR teams to understand.
Scenario 2 — Passing API Error to Global Fault Handler
An integration calls multiple downstream services.
Example flow:
↓
Invoke Fusion ERP API
↓
Invoke Payment Gateway
If the Payment Gateway API fails, the scope handler can:
Rethrow the fault
This allows the Global Fault Handler to:
Send notification emails
Log error in tracking table
Create incident ticket
Scenario 3 — Wrapping Technical Errors for External APIs
Sometimes OIC integrations act as public APIs.
Example:
External application calls OIC REST service.
If internal Fusion API fails, you may want to return:
“status”: “ERROR”,
“message”: “Supplier creation failed”
}
Instead of the internal error.
This is done using Throw New Fault.
Architecture / Technical Flow
Understanding how faults travel through OIC is important.
Fault Propagation Hierarchy
↓
Scope Fault Handler
↓
Global Fault Handler
↓
Integration Failure
If an error occurs:
Activity throws fault
Scope handler catches it
Scope handler decides:
Handle error
Throw new fault
Rethrow fault
Behavior Summary
| Fault Type | Result |
|---|---|
| Throw New Fault | Replaces the original fault |
| Rethrow Fault | Sends original fault to parent handler |
Prerequisites
Before implementing fault actions in OIC:
1. Access to OIC Gen 3 Instance
You must have access to:
Integrations → App Driven Orchestration
2. Required Roles
Integration Developer
Service Developer
3. Integration Design Knowledge
You should understand:
Scope actions
Fault handlers
REST/SOAP invokes
Step-by-Step Implementation in OIC Gen 3
Let’s walk through a practical example.
Example Integration
↓
Scope
↓
Invoke ERP Supplier API
We will simulate a fault and implement both:
Throw New Fault
Rethrow Fault
Implementing Throw New Fault
Step 1 — Create Integration
Navigate to:
Select:
Enter:
| Field | Value |
|---|---|
| Name | CreateSupplierIntegration |
| Identifier | create_supplier |
Click Create.
Step 2 — Configure REST Trigger
Add a REST Adapter.
Define:
Sample request payload:
“SupplierName”: “ABC Traders”,
“SupplierNumber”: “SUP1001”
}
Step 3 — Add Scope
Drag Scope action.
Rename it:
Scopes help isolate error handling.
Step 4 — Invoke Fusion API
Inside the scope:
Add Invoke
Adapter:
Operation:
Map input payload.
Step 5 — Configure Scope Fault Handler
Click the Scope → Fault Handler section.
Add action:
Step 6 — Configure Fault Message
Define a custom fault payload.
Example:
“errorCode”: “SUPPLIER_CREATE_FAILED”,
“errorMessage”: “Supplier creation failed in ERP”
}
This replaces the original API error.
Result
If ERP API fails:
Original Error:
Returned Response:
“errorCode”: “SUPPLIER_CREATE_FAILED”,
“errorMessage”: “Supplier creation failed in ERP”
}
Implementing Rethrow Fault
Now let’s see how to propagate the original fault.
Step 1 — Open Scope Fault Handler
Inside the Scope Fault Handler:
Remove Throw New Fault
Add action:
Step 2 — Configure Global Fault Handler
Open:
Add actions such as:
Send Email Notification
Write to Logging Table
Invoke Incident Management API
Example email:
Message:
Supplier creation integration failed.
Check instance ID: ${trackingId}
Result
When ERP API fails:
Flow becomes:
↓
Scope Handler
↓
Rethrow Fault
↓
Global Fault Handler
↓
Email Notification
Testing the Fault Handling
Testing is essential to validate behavior.
Test Scenario 1 — Invalid Supplier Data
Send request:
Payload:
“SupplierName”: “”,
“SupplierNumber”: “”
}
Expected behavior:
| Case | Expected Result |
|---|---|
| Throw New Fault | Custom error returned |
| Rethrow Fault | Global handler triggered |
Validate Instance Tracking
Navigate to:
Verify:
Error message
Fault location
Activity logs
Common Errors and Troubleshooting
Issue 1 — Fault Not Triggered
Cause:
Fault handler not configured at correct level.
Solution:
Check whether error occurs:
Activity level
Scope level
Issue 2 — Fault Message Not Returned
Cause:
Incorrect fault payload mapping.
Solution:
Verify JSON structure.
Issue 3 — Integration Stops Unexpectedly
Cause:
No Global Fault Handler defined.
Solution:
Always configure a global error strategy.
Best Practices from Real OIC Projects
1. Always Use Scopes for API Calls
Scopes isolate failures.
Example:
→ ERP API
Scope
→ Payment API
Each scope has its own handler.
2. Use Throw New Fault for Business-Friendly Errors
Avoid exposing internal system errors to external clients.
Example:
Bad:
Good:
3. Use Rethrow for Centralized Logging
Rethrow helps route errors to a single monitoring system.
This is essential for large integrations.
4. Maintain Consistent Error Format
Define enterprise error schema.
Example:
“errorCode”:””,
“errorMessage”:””,
“integration”:””,
“timestamp”:””
}
5. Log Technical Details Internally
While returning simplified errors externally, log detailed errors internally for troubleshooting.
Real Implementation Pattern Used in Enterprise Projects
Typical production architecture:
↓
Multiple Scopes
↓
Scope Fault Handler
↓
Rethrow Fault
↓
Global Fault Handler
↓
Error Logging Integration
This allows:
Centralized monitoring
Standardized error format
Automated notifications
Frequently Asked Questions (FAQ)
1. What is the difference between Throw New Fault and Rethrow Fault in OIC?
Throw New Fault creates a new custom error, while Rethrow Fault passes the original error to the parent fault handler without modification.
2. When should Throw New Fault be used?
Use Throw New Fault when:
You need a custom error message
The integration exposes public APIs
Technical errors should be hidden from business users
3. Does Rethrow Fault stop the integration?
No. It passes the error to the next available fault handler, usually the Global Fault Handler.
Summary
Handling failures correctly is a fundamental requirement in enterprise integrations built using Oracle Integration Cloud Gen 3.
Two important fault control actions available to developers are:
Throw New Fault
Rethrow Fault
These actions help determine how errors propagate through integration layers.
Key takeaways:
Throw New Fault replaces the original error with a custom message.
Rethrow Fault passes the existing fault to the parent handler.
Proper fault design improves integration reliability, monitoring, and user experience.
Combining scope handlers and global fault handlers creates a powerful error management architecture.
For deeper reference and official documentation, consult Oracle’s integration documentation: