Error Handling

CCP is using the OData standard and the OData standard uses standard HTTP in a RESTful way for communication. Therefore error handling is also mostly in line with default HTTP. It uses default HTTP response codes for the most part. This includes invalid or malformed requests, authentication errors, not found exceptions and many more.

Custom Exceptions

For the most part the HTTP response codes are enough for the most common exceptions. But in some cases more information is required for the client to properly handle exceptions. The OData specification has room for an extra payload in the error response. We use this capability to add custom exceptions. These custom exceptions are implemented using a generic specification. The response conforms to the requested wire-format using the Accept header. The exception always contains an object named error containing 2 properties code and message. Code contains the name of the custom exception. When the exception has extra parameters these are always encoded in json format and added to the message property. Details about all Custom Exceptions can be found in the reference section.

Payload in atom format

<?xml version="1.0" encoding="utf-8"?>
<m:error xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
  <m:code>ChangeReadOnlyResourceException</m:code>
  <m:message xml:lang="json">{"EntitySetName":"TripsSummary","EntityId":217465}</m:message>
</m:error>

Payload in json format

{
  "odata.error" : {
    "code" : "ChangeReadOnlyResourceException",
    "message" : {
      "lang" : "json",
      "value" : "{\"EntitySetName\":\"TripsSummary\",\"EntityId\":217465}"
    }
  }
}