Error Exceptions

When your API requests result in errors, the REST API returns exceptions. Let's familiarize ourselves these exceptions and look at some examples:

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

Exception Details

Here's the list of fields that you see when an exception occurs:

Field	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.

Here's an example of an exception message:

{
"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

You can view the list of exceptions available in the Service Could REST API using the following syntax.

Syntax URL

You can use the GET method with the following URL:

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

Response

Here's an example of the response body in JSON format.

{
    "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

You can view the details of a particular exception available in the Service Could REST API using the following syntax.

Syntax URL

You can use the GET method with the following URL:

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

Example URL

You can view the metadata details of exception OSC-CREST-00001 by using the GET method with the following URL:

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

Example Response

Here's an example of the response body in JSON format.

{
    "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 B2C Service 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'