7 Troubleshoot the REST Adapter

Review the following topics to learn about troubleshooting issues with the REST Adapter.

Topics:

Error Calling Oracle Cloud Infrastructure Object Storage When Using an Asterisk (*) in a File Name

If you are calling Oracle Cloud Infrastructure Object Storage, you cannot use the regular expression (regex) pattern language when listing objects. Instead, list objects by name or prefix.

For example, if your integration gets the file name from storage using an asterisk (for example, Full*.txt), an error occurs: 
interfaces/inbound/RPT/RPT_MSC_INTEG_112/Product - FDI - Full*.txt
Do not include the * character. Instead, specify the complete name: (Full.txt).
interfaces/inbound/RPT/RPT_MSC_INTEG_112/Product - FDI - Full.txt

See Searching for Object Storage Objects in a Bucket.

OAuth Returns a "The token has already been consumed" Error

When using the REST Adapter with the Authorization Code grant type and Oracle Cloud Infrastructure Identity and Access Management (identity domains) as the identity provider, the call can fail with the following exception. 

Failed retrieving access token using refresh token flow with error code [400] body: 
{"error":"invalid_grant","error_description":"**The token has already been consumed.**","ecid":"xxxxxxxxxxx"}.
When using the Authorization Code grant type, the following types of tokens are used.
Token Token Access Refresh Token
Purpose Call REST APIs Get new access tokens
Lifetime Short Long
Sent to Resource server (API) Authorization server only
Contains scopes Yes No

Connection Token Usage

Question Answer
How does a connection get a new access token and refresh token?
  1. Open the REST Adapter connection.
  2. Click Provide Consent.
  3. Log in to Oracle Cloud Infrastructure Identity and Access Management.

    The connection gets the following token information:

    • Access token (default Oracle Cloud Infrastructure Identity and Access Management token expiration is one hour)
    • Refresh token (default Oracle Cloud Infrastructure Identity and Access Management token expiration is one week)
How does an adapter gets the access token?
  1. When an integration makes a REST call, the adapter gets the access token from the connection.
  2. The connection checks if the access token has expired.
  3. If it did not expire, the adapter uses the existing access token (Authorization: Bearer access-token).
  4. If it did expire, the connection attempts to obtain a new access token using the refresh token. When the access token expires, the connection makes a call to Oracle Cloud Infrastructure Identity and Access Management with the refresh token to obtain a new access token and a new refresh token. This situation is where the The token has already been consumed exception can be generated.

To investigate this exception, check the following:

  1. Verify if the refresh token is received by the connection.
    Oracle Cloud Infrastructure Identity and Access Management does not send a refresh token to the connection if the scope does not contain offline_access.
    Scope: "scope_value offline_access".

    If offline_access is missing, the connection only receives the access token. The token is used during runtime until expiration. After that, all adapter calls fail.

  2. Verify if the refresh token expired.

    When the access token expires, the connection makes a call to Oracle Cloud Infrastructure Identity and Access Management with the refresh token to obtain a new access token and a new refresh token.

    If there were no adapter calls for a long period of time, the refresh token can expire.

    If an expired refresh token is used to get a new access token and refresh token, Oracle Cloud Infrastructure Identity and Access Management returns a The token has already been consumed error.

    Note:

    Oracle Integration does not know if a refresh token has expired. Oracle Cloud Infrastructure Identity and Access Management only returns the expiration time for the access token, and not for the refresh token.

    This can happen if you have integrations that do not run often (for example, schedule integrations that run every two weeks, monthly, quarterly, or yearly).

    The connection only attempts to refresh the tokens when a new adapter call is made. If there are no adapter calls, the connection does not attempt to obtain a new access token.

    To avoid this issue, increase the refresh token expiration time from Oracle Cloud Infrastructure Identity and Access Management for the confidential application used for OAuth.

Oracle Cloud Infrastructure Object Storage Search REST API Returns a 401 Unauthorized Status Response

The Oracle Cloud Infrastructure Object Storage Search API is returning the following fault:

<ns0:APIInvocationError xmlns:ns0="http://xmlns.oracle.com/cloud/generic/rest/fault/REST/GetFiles">
    <ns0:type/>
    <ns0:title/>
    <ns0:detail/>
    <ns0:errorCode/>
    <ns0:errorDetails>
        <ns0:type>http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2</ns0:type>
        <ns0:title>Unauthorized</ns0:title>
        <ns0:errorCode>401</ns0:errorCode>
        <ns0:errorPath>&lt;![CDATA[InboundJaxrsResponse{context=ClientResponse{method=GET, uri=https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace/b/object/o?prefix=/prefix/filename*.txt, status=401, reason=Unauthorized}}]]&gt;</ns0:errorPath>
        <ns0:instance>&lt;![CDATA[{"code":"NotAuthenticated","message":"The required information to complete authentication was not provided."}.The 401 error message is usually returned by services that requires user credentials. So if you have got this error then it pobably means you entered an invalid username or password. It may also be that one of the intermediaries (proxy, LBR) could be returning this code. Please note, test connection doesn't validate the credentials and even if it is successful, it may not be sufficient. As the parameters defined within the connection page are used to call the target endpoint REST API, which is configured as part of endpoint configuration, it is strongly recommended that the endpoint configuration that uses this connection is tested. Re-check or re-configure the connection with the correct set of credentials. Test connection is only used to validate the parameters defined within the connection page. 1) This includes REST API definition - we try to retrieve the API Definition to understand the resources within. 2) API Base URL - We ensure that the base URL is reachable and can be trusted by OIC. 3) OAuth Configuration - We obtain the access tokens and try to refresh the access token. ]]&gt;</ns0:instance>
    </ns0:errorDetails>
</ns0:APIInvocationError>

Ensure that the file you are searching for does not contain the * character in its filename.

Searching for objects in a bucket using methods such as partial name segments or wildcards (*) is not supported. For more details, see the Object Storage documentation.

Troubleshoot Oracle Cloud Infrastructure REST APIs Issues

This section provides a video that walks you through testing the Oracle Cloud Infrastructure APIs with Postman. It also describes how to invoke the APIs and troubleshoot issues.

Watch a Video

Watch a video that walks you through testing the Oracle Cloud Infrastructure APIs with Postman. The video explains how to perform the following:
  • Use the Oracle Cloud Infrastructure REST API Postman collection
  • Configure the Oracle Cloud Infrastructure credentials used for invoking the Oracle Cloud Infrastructure REST APIs
  • Use the Oracle Cloud Infrastructure Identity and Access Management REST API to create a new user in identity domains
  • Use the Oracle Cloud Infrastructure Object Storage REST API to get the namespace, list the buckets in a compartment, and create a new bucket

See Oracle Cloud Infrastructure Postman Collection.

Invoke the Oracle Cloud Infrastructure REST APIs in Two Different Ways from Oracle Integration

  • Oracle Cloud Infrastructure native call

    The native call can be performed only for Oracle Cloud Infrastructure Functions and Oracle Cloud Infrastructure Object Storage. See Call Category in Using Integrations in Oracle Integration 3.

  • REST Adapter call

    Use the REST Adapter to invoke any Oracle Cloud Infrastructure Service REST API by using the OCI Signature Version 1 security policy. See Oracle Cloud Infrastructure REST API Documentation.

If the call fails in the activity stream, follow these steps to identify what caused the issue.
Step Steps Description
1 Collect the failure call details from Oracle Integration. Use the activity stream to identify the request details and the response error. From the activity stream, collect the following information:
  • Endpoint URL
  • REST method
  • Request headers
  • Request payload
  • Response headers
  • Response payload

See Learn About the Payloads in the Activity Stream in Using Integrations in Oracle Integration 3.

2 Test the same call to the Oracle Cloud Infrastructure REST API outside of Oracle Integration.
  1. Use the Oracle Cloud Infrastructure Postman collection and find the same endpoint to call the Oracle Cloud Infrastructure REST APIs.
  2. Use the same request headers and payload to test the Oracle Cloud Infrastructure REST API.
  3. If the call is failing with the same error with Postman, it means that the issue is not related to Oracle Integration. Oracle Integration has no control over the response that Oracle Cloud Infrastructure returns. You must analyze and fix the call before attempting it from the integration.
  4. Verify the error returned by the Oracle Cloud Infrastructure REST API common errors for all services. See API Errors.
  5. Based on the error type, fix the issue and ensure that the call is successful with Postman.

    You can contact the Oracle Cloud Infrastructure team that is managing the REST API to assist you further and help you fix the error. While engaging the Oracle Cloud Infrastructure team, provide the details of the REST API call that you are making. Ensure that you provide the timestamp of the call and the value for the opc-request-id response header. The Oracle Cloud Infrastructure team can use the opc-request-id value to track your request and understand why the call is failing.

3 Update the Oracle Integration connection/integration with the same changes that fixed the issue in Postman.
  1. Verify the changes you made in Postman that caused the Oracle Cloud Infrastructure REST API call to succeed.
  2. Update the Oracle Integration connection and/or the integration with the same changes.
  3. Test the call from Oracle Integration to validate that the changes resolved the issue.
  4. If the call is successful with Postman and is still failing in Oracle Integration, contact Oracle Integration Support for further analysis. Ensure that you:
    • Share the details collected with Postman for the successful call
    • Export and attach the integration and connection details
    • Provide the instance ID and the activity stream

Invalid Reference Error When Uploading the XML Schema

When you upload an XML schema in the Adapter Endpoint Configuration Wizard and encounter an error similar to the following, this indicates that a namespace prefix conflict occurred in the generated artifacts of the REST Adapter with the schema provided. 

Error: ICS-10064 : An error occurred while preparing mapper object. Invalid reference

Solution: Change the prefix used in the uploaded schema to avoid conflicts. Do not use ns* prefixes because they are used internally by Oracle Integration during artifact generation.

ORABPEL-15235 Translation Failure Error Occurrence

If the string length for fields in a JSON payload exceeds 20 MB, a REST Adapter trigger connection fails with the following error: 

ORABPEL-15235 Translation Failure. Failed to translate JSON to XML. String length (20038094)
exceeds the maximum length (20000000) The incoming data does not conform to the NXSD schema. 
Please correct the problem
As a workaround, remodel your integration to work around this field size restriction. Some recommendations are:
  • Write a file to an external SFTP server for processing outside of Oracle Integration.
  • Add an attachment as a stream when invoking the endpoint rather than sending the content as a Base64-encoded string.

Failed REST Adapter Invoke Connection Retries Three Times Every 30 Seconds with a 504 Timeout Error

A REST Adapter connection attempting to invoke an external REST service retries three times approximately every 30 seconds upon receiving a 504 gateway timeout error.

The REST Adapter is designed to support the following types of retries:
  • Three retries for a 504 error (from an external service) for all cases.
  • Three retries for a 502 error (from an external service), but only for GET operations.
  • Three retries for SSL and adapter-marked retryable exceptions (with 500 milliseconds of sleep between each call).
  • Three retries for a 401 error.

You can also select to disable automatic retries of 504 errors. See Disable Automatic Retries of HTTP 504 Errors.

Troubleshoot RPST and OCI Service Invocation Security Policy Issues

Learn about troubleshooting configuration issues when using the Resource Principal Session Token (RPST) and the OCI Service Invocation security policy.

Error Cause of Error and Resolution

A 404 Not Found error occurs with the following message: 

[CDATA[{\"code\":\"NamespaceNotFound\",\"message\":\"You do not have authorization to perform this request, 
or the requested resource could not be found.\"}.The HTTP 404, 404 Not Found, and 404 error message is a Hypertext 
Transfer Protocol (HTTP) standard response code, in computer network communications, to indicate that the client 
was able to communicate with a given server, but the server could not find the resource that was requested. Carefully 
re-examine the target endpoint that is being called. ]]>
 You used the OCI Service Invocation security policy without setting the correct policy. For this example, the Get Object Storage Namespace operation worked, but other operations failed because the policy was not set to access or modify a compartment.

Set your policy to perform the required operations. See RPST and OCI Service Invocation Security Policy Use.

A 409 Not Found error occurs with the following message: 

[CDATA[{"code":"BucketAlreadyExists","message":"Either the bucket 'test-rpst-OICServiceInstance-phx-NoPermission' 
in namespace 'axkbv4jfb37h' already exists or you are not authorized to create it"}.This error usually indicates that the 
request submitted by Oracle Integration Cloud can not be completed because it conflicts with some rule already established 
by the service. This is usually a functional error. If the call to the target service using a cURL request is successful 
then contact oracle support with the details.
 A policy was created that only lets you read buckets in a compartment: 
allow dynamic-group rpst_oic-prod-phx-123_Dynamic_Group to read buckets in compartment oic-dev:pp-phx-123-comp

If you try to create a bucket in the compartment, it fails because the policy is not set to perform the required operation.

Create a policy that allows you to write to the bucket. See RPST and OCI Service Invocation Security Policy Use.

A 404 Not Found error occurs with the following message: 

<![CDATA[{\"code\":\"NamespaceNotFound\",\"message\":\"You do not have authorization to perform this request, or 
the requested resource could not be found.\"}.The HTTP 404, 404 Not Found, and 404 error message is a Hypertext Transfer 
Protocol (HTTP) standard response code, in computer network communications, to indicate that the client was able to communicate
 with a given server, but the server could not find the resource that was requested. Carefully re-examine the target endpoint 
that is being called. ]]>
 The Get Object Storage Namespace operation works, but other operations fail due to the dynamic group being specified as follows:
instance.id = service_instance_ocid
RPST expects the resource ID, not the instance ID, to be specified. Specify the resource ID and assign it the client ID of the OAuth application of your Oracle Integration instance when creating the dynamic group:
resource.id = 'client_ID'

See RPST and OCI Service Invocation Security Policy Use.

A 404 Not Found error occurs with the following message: 

<![CDATA[{\"code\":\"NamespaceNotFound\",\"message\":\"You do not 
have authorization to perform this request, or the requested resource could
not be found.\"}.The HTTP 404, 404 Not Found, and 404 error message is a 
Hypertext Transfer Protocol (HTTP) standard response code, in computer 
network communications, to indicate that the client was able to communicate 
with a given server, but the server could not find the resource that was 
requested. Carefully re-examine the target endpoint that is being called. ]]>
 The Get Object Storage Namespace operation works, but other operations fail due to the dynamic group being specified as follows:
resource.id = service_instance_OCID
Assign the client ID of the OAuth application of your Oracle Integration instance to the resource ID when creating the dynamic group:
resource.id = 'client_ID'
See RPST and OCI Service Invocation Security Policy Use.

Multipart Form-Data Endpoint Invocation Fails When Media Type is null

Ensure that the attachment properties - attachment content type is mapped with an appropriate value. The sample documentation for request mapping provides information.

See Map to Construct the Payload for an External REST API that Accepts multipart/form-data as the Content Type.

Convert a Private Key from PKCS8 to RSA (PKCS1) Format for the OCI Signature Version 1 Security Policy

Private keys downloaded from the Oracle Cloud Console are in PKCS8 format. The OCI Signature Version 1 security policy available with the REST Adapter only supports reading of the private key in RSA format (PKCS1 format).

If you receive the following error, you must convert the private key from PKCS8 to RSA (PKCS1) format.
CASDK-0005: A connector specific exception was raised by the application.
java.lang.ClassCastException: org.bouncycastle.asn1.pkcs.PrivateKeyInfo
cannot be cast to org.bouncycastle.openssl.PEMKeyPair;
org.bouncycastle.asn1.pkcs.PrivateKeyInfo cannot be cast to
org.bouncycastle.openssl.PEMKeyPair
  1. Convert the private key with the following command:
    openssl pkey -in private_key_in_pkcs8_format.pem -traditional > new_converted_file.key
    For example:
    openssl pkey -in pkcs8.pem -traditional > rsa.key
    An example of a PKCS8-formatted private key file:
    -----BEGIN PRIVATE KEY-----
contents
-----END PRIVATE KEY-----
    An example of an RSA (PKCS1)-formatted file after the conversion:
    
-----BEGIN RSA PRIVATE KEY-----
contents
-----END RSA PRIVATE KEY-----

HTTP Error Response for Pre-20.4.2 Connections is Not Compliant with the OpenAPI Specification

The HTTP error response returned by integrations created prior to release 20.4.2 (November 2020 quarterly release) that include a REST Adapter-based trigger connection does not strictly conform to the OpenAPI specification.

The error response returned has an o: prefixed to certain keys. For example:
{
  "type" :
"http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1",
  "title" : "Internal Server Error",
  "detail" : "An internal error occurred while processing the request. Please
see the fault details for the nested error details.",
  "o:errorCode" : "400",
  "o:errorDetails" : [ {
    "type" :
"http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5",
    "instance" : "<![CDATA[{}.The HTTP 404, 404 Not Found, and 404 error
message
is a Hypertext Transfer Protocol (HTTP) standard response code, in computer
network communications, to indicate that the client was able to communicate
with a given server, but the server could not find the resource that was
requested.
Carefully re-examine the target endpoint that is being called. ]]>",
    "title" : "Not Found",
    "o:errorPath" : "<![CDATA[GET http://api.zippopotam.us/us/9021011
returned a response status of 404 Not Found]]>",
    "o:errorCode" : "404"
  } ]
}

With the November 2020 release (20.4.2), the HTTP error response format has been modified for newly created integrations to be compliant with the OpenAPI specification. The o: previously prefixed to certain keys has been removed, as shown in the following message.

However, note that all existing, pre-20.4.2 integrations continue to have the same error response shown above, even when those integrations are modified.

{
  "type" :
"http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1",
  "title" : "Internal Server Error",
  "detail" : "An internal error occurred while processing the request. Please
see the fault details for the nested error details.",
  "errorCode" : "404",
  "errorDetails" : [ {
    "type" :
"http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5",
    "instance" : "<![CDATA[{}.The HTTP 404, 404 Not Found, and 404 error
message
is a Hypertext Transfer Protocol (HTTP) standard response code, in computer
network communications, to indicate that the client was able to communicate
with a given server, but the server could not find the resource that was
requested.
Carefully re-examine the target endpoint that is being called. ]]>",
    "title" : "Not Found",
    "errorPath" : "<![CDATA[GET http://api.zippopotam.us/us/9021011 returned a
response status of 404 Not Found]]>",
    "errorCode" : "404"
  } ]
}

REST Services that Return Multiple Successful Responses

The REST Adapter can be configured for only a single type of response. A service that returns multiple responses, even with different HTTP success status codes, is not supported. All except for the configured response type result in an APIInvocationError. You can catch the resulting error using a scope action and a fault handler if the fault is not required in the integration.

Error Handling with the REST Adapter

The REST Adapter uses the following strategy to handle errors in the invoke (outbound) and trigger (inbound) directions.

Error Handling in the Invoke (Outbound) Direction

The REST Adapter in the invoke (outbound) direction returns a standard APIInvocationError for any HTTP response that it receives with an error code. In addition, it also produces an APIInvocationError if a processing error occurs within the REST Adapter while preparing the request, calling the endpoint, or handling the response.

The format of the APIInvocationError in the mapper is as follows.
Description of error-details.png follows
Description of the illustration error-details.png

The errorDetails section contains the actual cause.

You can handle the APIInvocationError with a fault handler in the integration.

Error Handling in the Trigger (Inbound) Direction

The REST Adapter in the trigger (inbound) direction exposes an HTTP endpoint that HTTP clients can request for using an HTTP request, and returns an HTTP response.

If successful, the REST Adapter returns a success response. The REST Adapter returns an error response with an HTTP status belonging to the error family of codes depending on the situation. The following table describes the possible cause and the REST Adapter response.

Condition HTTP Status Details
Invalid client request 4xx

There are several conditions that can cause client side failures, including:

  • An invalid resource URL
  • Incorrect query parameters
  • An unsupported method type
  • An unsupported media type
  • Bad data
Downstream processing errors 5xx

All other errors that can occur within the integration, including:

  • An invalid target
  • An HTTP error response
  • General processing errors

In addition, the REST Adapter also returns an error response with additional details about the error and possible steps for troubleshooting. The standard error response format is returned according to the configured response media type. The following is a sample JSON response structure: 

{
  "type" : "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1",
  "title" : "Internal Server Error",
  "detail" : "An internal error occurred while processing the request. Please see the fault details for the nested error details.",
  "o:errorCode" : "500",
  "o:errorDetails" : [ {
    "type" : "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1",
    "instance" : "{\n   \"error_message\" : \"Invalid request. Missing the 'origin' parameter.\",\n   \"routes\" : [],\n   
    \"status\" : \"INVALID_REQUEST\"\n}\n",
    "title" : "Bad Request",
    "o:errorPath" : "GET http://maps.googleapis.com/maps/api/directions/json?destination=Montreal returned a response status of 
      400 Bad Request",
    "o:errorCode" : "APIInvocationError"
  } ]
}

The o:errorDetails section is reserved for the actual cause. The prefix o: included is based on Oracle standards.

The top portion is used to add any integration-specific details to the fault. This is typically not necessary, but if you want to control the HTTP status, title, and details, set these values appropriately. If not entered, sufficient default values are provided by the REST Adapter.

Note:

The REST Adapter returns the downstream errors with a 500 Internal server error code. You can override these errors and provide a custom error code by assigning an appropriate value to APIInvocationError/errorCode in the target mapper.

The suggested mappings to map faults raised by an outbound system to the trigger (inbound) REST Adapter are as follows:


Description of error-mapper.png follows
Description of the illustration error-mapper.png

The top section is left out in this mapping and these are appropriately assigned by the REST Adapter in the previously described sample.

Unmapped faults are propagated as system faults by Oracle Integration to the inbound REST Adapter. They may not communicate the appropriate details. Therefore, it is recommended that you define the fault pipelines.

REST Service Invoked by the REST Adapter Returns a 401 Unauthorized Status Response

If a REST service invoked using the REST Adapter consistently returns a response status of 401 Unauthorized, it may be because the application credentials configured on the Connections page are no longer valid.

The Connections page does not validate the credentials. Even if the test connection is successful, it may not be sufficient because the test connection only validates the parameters defined on the Connections page.

Because the parameters defined on the Connections page are used to call the target endpoint REST API, which is configured as part of endpoint configuration, it is strongly recommended that you test the endpoint configuration that uses this connection.

Configuration Limitation of Ten Pages in the Adapter Endpoint Configuration Wizard

Note the following issue with the REST Adapter multiple resources per endpoint use case in the Adapter Endpoint Configuration Wizard.

Symptom Workaround Reason
A refresh issue may occur when configuring multiple verbs and resources for the REST Adapter as a trigger connection in the Adapter Endpoint Configuration Wizard. If the wizard does not refresh while configuring multiple operations, click Back to return to a previous page and then press Next to refresh to the current page. The REST Adapter multiple sources per endpoint use case requires multiple iterations over the same sets of pages. This is currently a technical restriction.

Keys with Null Values During JSON Transformation are Removed

The REST Adapter removes keys with null values during JSON transformation.

For example, if the following JSON payload is sent to the REST Adapter:

{
"input" : "input",
"val" :  null,
"response": "response"
}
Oracle Integration sends the outbound request with the following JSON output.
{
"input" : "input",
"response": "response"
}

If you need the key available at the outbound service, use the following payload:

{
"input" : "input",
"val" :  "",
"response": "response"
}

Large Sample JSON File Processing with Special Characters

The sample JSON file is typically large when it has repeating structures. You can purge such repetitions because the sample only needs to represent the structure and not the instance document. However, if the JSON file is unusually large and cannot be trimmed, perform the following the steps:

  1. Replace all occurrences of special characters (for example, $) with their corresponding codes in the sample JSON file. See JSON to XML Special Character Conversion.
  2. Use the modified JSON file to complete the configuration.
  3. Select the generated schema in the Adapter Endpoint Configuration Wizard.
At runtime, incoming instances of JSON documents with keys having special characters are normalized to suitable XML element names and XML documents having these elements when serialized are converted to JSON documents with special characters restored in the key names.

Troubleshoot SSL Issues

Use the following information to troubleshoot SSL connection issues.

SSL Exception Cases

Review the following types of SSL errors, and their symptoms, likely causes, and resolutions.

  • SSLHandshakeException: PKIX path building failed
    Common full pattern:
    javax.net.ssl.SSLHandshakeException
sun.security.provider.certpath.SunCertPathBuilderException:
unable to find valid certification path to requested target

sun.security.validator.ValidatorException:
PKIX path building failed
    Field Details
    What is the error Oracle Integration cannot validate the server certificate chain. A required root or intermediate certificate is missing from the Oracle Integration trust store.
    Symptoms The adapter test connection fails before receiving an application response. Logs show the following:
    PKIX path building failed, unable to find valid certification path, or ValidatorException

    The browser may show a certificate warning for the endpoint.
    Likely causes The server uses a self-signed certificate, private certificate authority (CA), lesser-known CA, missing intermediate certificate, or new CA not present in the JDK default cacerts.
    Resolution
    • Download the server trust chain.
    • Upload the required root/intermediate certificates into Oracle Integration as a Trust certificate. Select Home, then Settings, then Certificates.
    • Retest the connection.

    Do not upload the server public certificate as an Identity certificate. This is a trust problem.

  • Host Name/Subject Alternative Name (SAN) Mismatch
    Typical patterns:
    No name matching host found
CertificateException: No subject alternative DNS name matching host
HTTPS hostname wrong
    Field Details
    What is the error The certificate is valid cryptographically, but was not issued for the host name or IP address used by the adapter endpoint.
    Symptoms
    • The SSL handshake fails.
    • The logs mention host name verification, SAN, CN, or name mismatch.
    • The openssl s_client may show a certificate whose subjectAltName does not include the endpoint host.
    Likely causes
    • The endpoint uses an IP, but the certificate only has DNS SAN.
    • The endpoint uses DNS, but the certificate SAN has a different name.
    • The wildcard does not cover the requested host.
    • The certificate only has CN, and no proper SAN.
    Resolution Use the host name present in the certificate SAN or coordinate with the endpoint owner to issue a corrected certificate with the right DNS/IP SAN. For IP endpoints, the IP must be present as an IP SAN.
    Check the following:
    openssl s_client -connect host:443 -servername host -showcerts 
openssl x509 -in server.crt -text -noout
    Look for:
    X509v3 Subject Alternative Name
DNS expected-host
IP Address:expected-ip
    Example: Generation of a certificate with the keytool specifying SAN (used mostly for self-signed certificates):
    keytool -genkey -alias myAlias -keyalg RSA -keystore myKeyStore -keyalg RSA -validity 9999 -dname "CN=FQDN/IP, O=oic, L=RWS, S=CA, C=US, OU=oracle usa" -ext "san=DNS1:test,DNS2:localhost,IP:127.0.0.1"
  • Expired Or Not-Yet-Valid Certificate
    Typical patterns:
    CertificateExpiredException
CertificateNotYetValidException
NotAfter
NotBefore
    Field Details
    What is the error The certificate validity window does not include the current time.
    Symptoms
    • The adapter test fails with a certificate validity exception.
    • The openssl x509 -text command shows an expired Not After or a future Not Before.
    Likely causes The server certificate expired, the renewed certificate was not deployed, a system clock issue occurred, or a new certificate was activated too early.
    Resolution You must renew/redeploy the server certificate. If Oracle Integration uses an uploaded trust chain, verify that the renewed chain still links to the trusted root/intermediate certificates.
    Command to run:
    openssl x509 -in certificate -noout -dates
  • Weak or Unsupported Certificate Algorithms
    Typical patterns:
    Algorithm constraints check failed
Unsupported signature scheme
No available authentication scheme
key algorithm does not match
    Field Details
    What is the error Certificate algorithm, key length, signature algorithm, or TLS/cipher negotiation is incompatible with the Java/Oracle Integration SSL stack or endpoint requirements.
    Symptoms The SSL debug logs show unsupported schemes such as DSA variants, No available authentication scheme, No X.509 cert selected, or Ignore alias certificate: key algorithm does not match.
    Likely causes
    • Old/weak certificate
    • MD5/SHA1 signature
    • Small RSA key
    • DSA certificate
    • EC/RSA mismatch
    • The server requires a certificate algorithm not available in the uploaded identity keystore
    Resolution Use a certificate with supported modern algorithms. Preferably, RSA 2048+ or the algorithm explicitly required by the server. You must recreate the identity keystore with the correct key algorithm and import the full chain.
  • TLS Version Mismatch
    Typical patterns:
    protocol_version
handshake_failure
No appropriate protocol
Received fatal alert: protocol_version
    Field Details
    What is the error The client and server cannot agree on a TLS protocol version.
    Symptoms
    • The handshake fails before certificate validation completes.
    • The endpoint works only with old TLS versions or rejects the version that Oracle Integration uses.
    Likely causes The server only supports TLS 1.0/1.1 or the server has disabled TLS 1.2+.
    Resolution
    • Ensure that both Oracle Integration and the endpoint support TLS 1.2 or above.
    • Enable TLS 1.2+.

HTTP 401/403 For Identity Certificates

This category usually means TLS completed, but the server rejected the client identity or authorization.
Field Details
What is the error The endpoint requires client certificate authentication or certificate-based authorization, and the identity certificate sent by Oracle Integration is missing, not trusted, expired, unauthorized, or mapped incorrectly.
Symptoms
  • The adapter connection reaches the server and receives an HTTP 401 Unauthorized or 403 Forbidden error.
  • The SSL handshake may appear successful.
  • The browser/curl command with the correct client certificate may work, while Oracle Integration fails.
Likely causes
  • The wrong identity certificate alias was selected in the adapter connection.
  • The identity certificate was uploaded under the wrong category.
  • The server does not trust the client certificate issuer.
  • The client public certificate was not registered on the server.
  • The certificate DN/fingerprint is not mapped to an authorized user/application.
  • The keystore contains only public certificate entries, and not a private key.
Resolution
  • Verify the Oracle Integration certificate is uploaded as Identity.
  • Confirm the adapter two-way SSL is enabled and the selected alias matches the uploaded identity alias.
  • Confirm the JKS contains a PrivateKeyEntry.
  • Provide the exported public client certificate to the endpoint owner and ask them to trust/map it.
  • Confirm the root/intermediate chain is accepted by the server.
Support checks:
keytool -list -v -keystore identityKeystore.jks
Look for:
Entry type: PrivateKeyEntry

If it says trustedCertEntry, it is not a valid mTLS identity keystore.

Test outside Oracle Integration:
curl -v --cacert rootCA.crt --key client.key --cert client.crt https://host/path

If the curl command succeeds with the same certificate, but Oracle Integration receives a 401/403 error, check the Oracle Integration alias/category/passwords and whether the endpoint is authorizing the exact certificate that Oracle Integration sends.

HTTP 500 For Identity Certificate Mismatch

Field Details
What is the error The server or upstream application encountered an internal error while processing the presented client certificate, typically because the certificate does not match what the server expects.
Symptoms
  • Oracle Integration receives an HTTP 500 message after SSL/mTLS negotiation.
  • The SSL debug may show Oracle Integration sent a certificate, but the application still fails.
  • Server-side logs may show a client DN mismatch, issuer mismatch, fingerprint mismatch, subject mismatch, missing certificate mapping, or certificate chain validation error.
Likely causes
  • The wrong identity alias was selected.
  • The certificate subject/issuer/fingerprint does not match server configuration.
  • The server expects a different public certificate than the one in Oracle Integration.
  • The certificate was renewed in Oracle Integration, but not updated on the server allowlist.
  • The private key and certificate chain do not correspond.
  • There was an intermediate/root chain mismatch.
Resolution
  • Compare the certificate actually uploaded/selected in Oracle Integration with the certificate registered on the server.
  • Match the SHA-1/SHA-256 fingerprint, subject DN, issuer DN, serial number, and validity.
  • Re-upload the correct JKS as Identity, select the correct alias on the connection, and ask the endpoint owner to update the allowlist/mapping if the certificate changed.
Useful fingerprint commands:
openssl x509 -in client.crt -noout -fingerprint -sha1
openssl x509 -in client.crt -noout -fingerprint -sha256
keytool -list -v -keystore identityKeystore.jks -alias alias
Check whether the identity keystore was built correctly:
keytool -list -v -keystore identityKeystore.jks
Expected output:
Alias name: alias-used-in-OIC
Entry type: PrivateKeyEntry
Certificate chain length: leaf + intermediate/root

Decision Matrix

Observed Issue Most Likely Area Action
PKIX path building failed Trust certificate Upload server root/intermediate certificates as Trust in Oracle Integration.
Host name/SAN error Server certificate Use the correct host name or ask the server owner to reissue the certificate with the correct SAN.
Expired/not valid Server or client certificate validity Renew/redeploy the certificate.
No available authentication scheme Identity certificate algorithm/private key Recreate the identity certificate/keystore with a compatible key and PrivateKeyEntry.
HTTP 401 Client certificate is missing or unauthenticated Verify the mTLS alias, identity category, private key, and server trust.
HTTP 403 Client certificate is authenticated, but unauthorized Ask the endpoint owner to authorize/map the certificate subject/fingerprint.
HTTP 500 after mTLS Server-side certificate mismatch Compare the Oracle Integration certificate with the server expected certificate and update the mapping/allowlist.

Escalation Checklist

Before contacting Oracle Integration support, collect the following:
  • Full Oracle Integration connection test error.
  • HTTP response code and response body, if available.
  • SSL debug snippet around CertificateRequest, certificate selection, and failure.
  • The output of the following command:
    openssl s_client -connect host:443 -servername host -showcerts
  • For mTLS, the sanitized output of the following:
    keytool -list -v -keystore identityKeystore.jks
    • Confirmation of the Oracle Integration certificate upload category: Trust or Identity.
    • The alias selected in the adapter connection.
    • Whether the browser/curl test with the same client certificate succeeds.

SSL Certification Troubleshooting Issues

  • Go to the Settings > Certificates tab and upload the server certificate.

  • For exception errors that occur when configuring a connection with OAuth Client Credentials or OAuth Resource Owner Password Credentials:

    Carefully review the OAuth documentation and use the Custom Two-Legged security policy.

  • For exception errors that occur when configuring a connection with OAuth Authorization:

    Carefully review the OAuth documentation and use the Custom Three-Legged Security Policy.

Fault and Response Pipeline Definitions in Basic Routing Integrations

You can define REST Adapter fault and response pipelines in Basic Routing integrations.

The REST Adapter on the trigger (inbound) side exposes an HTTP endpoint that HTTP clients can request for using an HTTP request, and returns an HTTP response.

If successful, the REST Adapter returns a success response. The REST Adapter returns an error response with an HTTP status belonging to the error family of codes depending on the situation. This table describes the possible cause and the REST Adapter response.

Condition HTTP Status Details
Invalid client request 4xx There are several conditions that can cause client side failures, including:

  • Invalid resource URL

  • Incorrect query parameters

  • Unsupported method type

  • Unsupported media type

  • Bad data
Downstream processing errors 5xx All other errors that can occur within the integration, including:

  • Invalid target

  • HTTP error response

  • General processing errors.

In addition, the REST Adapter also returns an error response with additional details about the error and possible steps for troubleshooting. The standard error response format is returned according to the configured response media type. The following is a sample JSON response structure: 

{
  "type" : "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1",
  "title" : "Internal Server Error",
  "detail" : "An internal error occurred while processing the request. Please see the fault details for the nested error details.",
  "o:errorCode" : "500",
  "o:errorDetails" : [ {
    "type" : "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1",
    "instance" : "{\n   \"error_message\" : \"Invalid request. Missing the 'origin' parameter.\",\n   \"routes\" : [],\n   
    \"status\" : \"INVALID_REQUEST\"\n}\n",
    "title" : "Bad Request",
    "o:errorPath" : "GET http://maps.googleapis.com/maps/api/directions/json?destination=Montreal returned a response status of 
      400 Bad Request",
    "o:errorCode" : "APIInvocationError"
  } ]
}

The errorDetails section is reserved for the actual cause. You must configure the fault pipelines to map the target faults into this element. The top portion is used to add any integration-specific details to the fault. This is typically not necessary, but if you want to control the HTTP status, title, and details, then set these values appropriately. If not entered, sufficient default values are provided by the adapter.

The suggested mappings to map faults raised by an outbound system to the trigger (inbound) REST Adapter are as follows:


Description of ics-rest-fault-hanlder.png follows
Description of the illustration ics-rest-fault-hanlder.png

The top section is left out in this mapping and so these are appropriately assigned by the adapter in the previously described sample.

Unmapped faults are propagated as system faults by Oracle Integration to the inbound adapter. They may not communicate the appropriate details. Therefore, it is recommended that you define the fault pipelines.

Note:

Fault pipelines are only available with Basic Map Data integrations.

Empty Arrays Are Not Supported in Sample JSON Files

When configuring the REST Adapter, if a JSON property in the included JSON sample file has an empty array, you receive the following error message. Note the last part of the message. Modify the JSON sample file to include a value for the JSON property.


Description of ics-rest-json-empty-ary.png follows
Description of the illustration ics-rest-json-empty-ary.png

Invoke Endpoint URI Must Match the Base URI + Resource URI in REST Adapter

While designing the REST Adapter in the Adapter Endpoint Configuration Wizard, carefully review the contents on the Summary page. The endpoint URI must match the invoke service URI. If you do not see the necessary values, review your invoke connection and the outbound service. The base URI in the connection and resource URI in the invoke service must add up to the endpoint URI.

JD Edwards Form Service Invocation with the REST Adapter Causes APIInvocation Error

You can receive the following error in the icsServer-diagnostic.log file when invoking JD Edwards Form Service from an integration in which a REST Adapter is configured as the invoke connection. 

[2016-06-07T02:13:54.346-07:00] [icsServer] [ERROR] [] 
[oracle.osb.transports.jca] [tid: [ACTIVE].ExecuteThread: '14' 
for queue: 'weblogic.kernel.Default (self-tuning)'] [userId: <anonymous>] 
[ecid: f23c428c-9247-459c-bb9f-22cbadbeda35-0003651d,0] [APP: Service Bus JCA 
Transport Provider] [oracle.soa.tracking.FlowId: 59] [FlowId: 
0000LKe8vtD7MAW5Hzw0yf1NGeIK00001c] Error sending bytes to socket: 
<genericRestFault><errorCode>500</errorCode><errorPath><![CDATA[POST 
http://den60208jems.my_domain.com:9516/jderest/formservice returned a 
response status of 500 Internal Server Error]]></errorPath><instance><![CDATA[{[[   
"message" : "Can not deserialize instance of java.util.ArrayList out of 
START_OBJECT token\n at [Source: java.io.StringReader@68f2c85d; line: 1, column: 
218] (through reference chain: 
com.oracle.e1.jdemf.FormRequest[\"formInputs\"])",   "exception" : "com.fasterxml.jackson.databind.JsonMappingException",   
"timeStamp" : "2016-06-07:03.13.54" }]]></instance></genericRestFault> 
]]
This error occurs because the REST Adapter has only one array element. JSON documents containing arrays in the REST Adapter require at least two array elements for the adapter to generate a valid XML schema. For example:
"formInputs": [ "input1" ]
cannot be handled as an array unless another cell is added in the sample JSON:

"formInputs": [ "input1", "input2" ]

REST Adapter Data is Only Saved When You Click Next

When configuring the REST Adapter in the Adapter Endpoint Configuration Wizard, you must click Next to save your changes and move to the next page of the wizard. For example, if you configure details on the Request page, click the tab of the Basic Info page in the left pane, then click Next to return to the Request page, none of your previous configurations were saved, and the page is empty.

Convert XML to a JSON Document

You can convert XML to a JSON document. Oracle Integration resolves an XML element with a number value to XML schema with a type of number, which converts the XML to a JSON document with a type of number.

For example:

  • XML:

    <Phone>23249480</Phone>

  • Generated XSD:

    <element name="phone" type="integer"/>

  • JSON:

    "Phone": 23249480

The workaround is to use a string value for the phone number in the sample XML. The XML schema generated has a type of string. At runtime, the XML to JSON conversion produces the desired JSON. For example:

  • XML:

    <Phone>a23249480</Phone> <!-- modified -->

  • Generated XSD:

    <element name="phone" type="string"/>

At runtime:

  • XML

    <Phone>23249480</Phone>

  • JSON

    "Phone": "23249480"

Supported Special Characters in JSON Samples

The following special characters are supported in JSON samples.

  • " " (blank space)

  • /

  • \\

  • ;

  • (

  • )

  • &

  • ,

  • #

  • ?

  • <

  • >

content-type is Missing for an Asynchronous Flow

The content-type is missing for an asynchronous flow.

Assume you create the following integration:

  1. Configure a REST Adapter connection with another Oracle Integration REST endpoint.

  2. Configure a trigger REST Adapter and an invoke REST Adapter with an asynchronous flow.

  3. Activate and invoke the integration.

    The content-type is missing.

    The content-type is ideally not required when the content-length is 0, but content-type text/plain is added as the default content-type by some layers. Both are correct and permissible.

REST URLs Exceeding 8251 Characters Fail

The upper limit of characters that work in REST URLs in integrations with the REST Adapter is 8251. If you exceed this limit, a 414 Request-URI Too Large error occurs.

Send a "null" Value Instead of "" for Any Specific Key in JSON Through the REST Adapter

If you want to send a "null" value instead of "" for any specific key in JSON through the REST Adapter, you must map "xsi:nil=true" through the mapper for that specific key.