Error Exceptions

Requests that result in errors return exceptions. For more information, refer to the following sections:

• Exception Details
• Retrieving the List of Exceptions
• Retrieving Individual Exceptions
• Handling Exceptions in PHP

Exception Details

The following table lists the exception details fields:

Topic	Description
type	Error type
title	Summary title for error
status	HTTP response code: 4xx: client-side error 5xx server error
detail	Detailed error message
instance	URI that provides more details
error code	Error code with the format OSC-CREST-#####, where ##### is a 5-digit number. For more information, see Error Codes.

The following is an example of an exception:

{
"type": "https://mysite.example.com/services/rest/connect/exceptions/OSC-CREST-00006",
"title": "An attempt to write a resource failed",
"status": 400,
"detail": "A problem setting a property to reference another object was encountered:
Invalid ID: No such Contact with ID = 209",
"instance": "https://mysite.example.com/services/rest/connect/v1.4/incidents",
"o:errorCode": "OSC-CREST-00006"
}

Retrieving the List of Exceptions

Use the GET method with the following URI to view the list of exceptions:

https://your_site_interface/services/rest/connect/exceptions

This request returns, for example:

{
    "items": [
    {
        "rel": "canonical",
        "href": "https://mysite.example.com/services/rest/connect/exceptions/OSC-CREST-00000"
        },
    {
        "rel": "canonical",
        "href": "https://mysite.example.com/services/rest/connect/exceptions/OSC-CREST-00001"
        },
        ...
    {
        "rel": "canonical",
        "href": "https://mysite.example.com/services/rest/connect/exceptions/OSC-CREST-00033"
        }
    ]
}

Retrieving Individual Exceptions

Use the GET method with the following URI to view an exception:

https://your_site_interface/services/rest/connect/exceptions/exception_num

For example:

https://mysite.example.com/services/rest/connect/exceptions/OSC-CREST-00001

Returns the metadata for exception OSC-CREST-00001:

{
    "type": "https://mysite.example.com/services/rest/connect/exceptions/OSC-CREST-00001",
    "title": "An unrecognized exception code was used",
    "status": 200,
    "detail": "Exceptions have the format of OSC-CREST-#####
    where ##### is replaced with a 5-digit numeric value. The numeric value
    passed in does not correspond to any known exception at this time.
    Future exceptions may be added which might use this code.",
    "instance": "https://mysite.example.com/services/rest/connect/exceptions/OSC-CREST-00001",
    "o:errorCode": "OSC-CREST-00001"
}

Handling Exceptions in PHP

You can use the REST API in an application written in PHP code to access Oracle Cloud from a web page. In this example, we try to retrieve the details of a Contact object using PHP. Using a web page, we enter a contact's ID. Clicking the Get Data button retrieves the details of that contact if it exists, and returns an exception if the contact does not exist.

To retrieve the details of a Contact object and handle exceptions using PHP:

1. Create a web page using HTML and PHP by using a text editor such as Notepad++.
2. Use curl in the "try" block to make the request to the REST URL endpoint. For example:

   try {
   $response = curl_exec($ch);
   }

3. Use the "catch" block to handle exceptions. For example:

   catch (Exception $e) {
   echo 'Catch error message: ' .$e->getMessage();
   }

4. If the call goes through, but the server sees something wrong with the request and returns an error message, the "catch" block will be skipped. In that case, check if there was a problem accessing the site due to a protocol problem or a host problem. For example:

   if (curl_errno($ch))
   print "Error accessing site: errno:  ".curl_error($ch);
   curl_close($ch);

5. Other possibility could be that the response was from the REST service itself, for example, where a resource does not exist or you are not authorized to access it. In that case, check the response. For example:

   $info = json_decode($response);

6. Save and close the HTML file.
7. Open the HTML page in a web browser.
8. Entering a valid contact ID displays the data about that contact.
9. Entering a contact ID that does not exist, returns an exception. For example, the following response displays HTTP status code 404, meaning "Not Found":

   Raw response:
   {"type": "https://mysite.example.com/services/rest/connect/exceptions/OSC-CREST-00013", "title": "Unrecognized resource", "status": "404", "detail": "Resource with id 33 not found", "instance": " https://mysite.example.com/services/rest/connect/v1.3/contacts/33", "o:errorCode": "OSC_CREST-00013" }
   HTTP Status Code: 404
   Oracle exception detail: Resource with id 33 not found

10. Entering a non-number, such as "xxx" returns another exception. For example, the following response displays HTTP status code 400, meaning "Bad Request":

    HTTP Status Code: 400
    Oracle exception detail: Illegal/malformed id 'xxx'