Troubleshoot the REST Adapter

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

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.

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 Infrastructure 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

Convert the private key with the following command:

openssl rsa -in private_key_in_pkcs8_format.pem -out new_converted_file.pem

For example:

openssl rsa -in private_key_pkcs8.pem -out private_key_rsa.pem

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

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

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 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:

Replace all occurrences of special characters (for example, $) with their corresponding codes in the sample JSON file. See JSON to XML Special Character Conversion.
Use the modified JSON file to complete the configuration.
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.

SSL Certification Troubleshooting Issues

For SSL certificate errors, perform the following tasks.

Topics

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:

Configure a REST Adapter connection with another Oracle Integration REST endpoint.
Configure a trigger REST Adapter and an invoke REST Adapter with an asynchronous flow.
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.