Error Handling & Context

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_tap_oracle_oic/errors.py
• src/flext_tap_oracle_oic/_models/_error_context.py
• src/flext_tap_oracle_oic/tap.py
• src/flext_tap_oracle_oic/models.py
• src/flext_tap_oracle_oic/constants.py
• src/flext_tap_oracle_oic/_models/_api_response.py

The Error Handling and Context system within the flext-tap-oracle-oic project provides a robust framework for managing, classifying, and recovering from failures encountered during interactions with the Oracle Integration Cloud (OIC) API. It leverages standardized exception hierarchies and detailed context models to ensure that errors are not only logged but also enriched with actionable recovery guidance for the Singer tap.

This system is built upon flext-core factory patterns, consolidating exception handling into a structured hierarchy that integrates with logging and error tracking services. It distinguishes between various error types—such as authentication failures, rate limits, and server-side issues—applying specific severity levels and retry logic to each.

Sources: src/flext_tap_oracle_oic/errors.py:1-12, src/flext_tap_oracle_oic/_models/_error_context.py:15-20

Exception Hierarchy

The project implements a specific set of exceptions that inherit from the flext-core base exception classes. This ensures compatibility with the broader FLEXT ecosystem while providing OIC-specific error types.

Exception Class	Base Class	Description
FlextTapOracleOicAuthenticationError	e.AuthenticationError	Raised when OAuth2 or IDCS authentication fails or tokens expire.
FlextTapOracleOicConnectionError	e.ConnectionError	Raised when network connectivity to the OIC endpoint is lost.
FlextTapOracleOicValidationError	e.ValidationError	Raised when data validation against schemas or models fails.
FlextTapOracleOicApiError	e.OperationError	General exception for OIC API operation failures.

Sources: src/flext_tap_oracle_oic/errors.py:19-35

Error Context Modeling

The OicErrorContext model is a Pydantic-based entity used to capture the granular details of a failure. It includes the HTTP status code, request parameters, and classification of the error to facilitate automated recovery.

Severity Determination

The system automatically classifies error severity based on the error_type and http_status_code:

• CRITICAL: AUTHENTICATION or AUTHORIZATION errors.
• WARNING: RATE_LIMIT, NETWORK, or VALIDATION errors.
• ERROR: SERVER_ERROR.

Sources: src/flext_tap_oracle_oic/_models/_error_context.py:112-125

Error Classification Flow

The following diagram illustrates how the system classifies incoming API errors and determines the next recovery step.

Explanation: This flowchart demonstrates the logic used within the OicErrorContext and OICBaseStream to categorize errors and initiate recovery strategies.
Sources: src/flext_tap_oracle_oic/_models/_error_context.py:82-125, src/flext_tap_oracle_oic/models.py:346-368

API Response Validation

The OicApiResponse model acts as a standardized wrapper for all OIC API communications. It handles both successful payloads and error metadata, ensuring that failed responses always contain mandatory error information.

Response Summary Logic

The api_response_summary computed field provides a high-level overview of the response state:

• response_status: Contains success indicators, timestamps, and correlation IDs.
• pagination: Determines if more data is available based on total_count and page_size.
• error_info: Summarizes error codes and messages when success is false.

Sources: src/flext_tap_oracle_oic/_models/_api_response.py:73-100

# Validation logic ensuring failed responses are documented
@u.model_validator(mode="after")
def validate_api_response(self) -> Self:
    """Validate OIC API response."""
    if not self.success and not self.error_message:
        msg = "Failed responses must have an error message"
        raise ValueError(msg)
    return self

Sources: src/flext_tap_oracle_oic/_models/_api_response.py:102-111

Stream Error Handling

Within the OICBaseStream, the _handle_response_error method maps HTTP status codes to the specific exception classes defined in the errors module.

Explanation: The sequence diagram shows the mapping process from HTTP response codes to specialized internal exceptions during stream execution.
Sources: src/flext_tap_oracle_oic/models.py:346-368, src/flext_tap_oracle_oic/constants.py:79-82

Constants and Thresholds

The error handling behavior is governed by specific thresholds defined in the constants module.

Constant	Value	Description
HTTP_ERROR_STATUS_THRESHOLD	400	The status code at which a response is considered an error.
MAX_RETRIES	3	Default maximum retry attempts for transient errors.
HTTP_RATE_LIMITED	429	The specific code triggering rate-limiting logic.
SLOW_RESPONSE_THRESHOLD	5.0	Seconds after which a response is logged as slow.

Sources: src/flext_tap_oracle_oic/constants.py:36-90

Conclusion

Error handling in the Oracle OIC tap is a multi-layered system that combines Pydantic models for context capture with a strict exception hierarchy. By centralizing these patterns, the tap provides consistent behavior across all streams (Integrations, Connections, etc.), ensuring that temporary API issues are handled via retries while critical authentication failures are reported immediately with full context.

Sources: src/flext_tap_oracle_oic/tap.py:270-285, src/flext_tap_oracle_oic/models.py:316-330