A com.betfair.cougar.core.api.fault.Fault happens under the following conditions:

The request is badly formed in some way (invalid encoding, mandatory data missing, etc)
The Cougar framework had an unexpected problem (a Java runtime exception).
The application code returned a defined exception (One of the exceptions listed in the <exceptions> tag of the operation).
The application code had an unexpected problem (a Java runtime exception).

It contains:

A FaultCode indicating whether the problem is at the client or on the server
An errorCode in the form XXX-YYYY, where XXX indicates in which functional area the error occurred, and YYYY is a number signifying the cause
A FaultDetail containing a message and possibly a trace, if detailed fault reporting is enabled

Enabling Detailed Fault Reporting

You can do this statically by setting the Cougar core property cougar.fault.detailed=true, or dynamically using the MBean CoUGAR:name=faultController.

Cougar errorCodes

DSC is the errorCode prefix for faults returned by Cougar itself.

If you can't find what you need in this table, please look at the source of `ServerFaultCode` in your IDE and then update this page.

Meaning	FaultCode	Client/Server	Associated HTTP Transport Response Code	Comments
DSC-0001	StartupError	Server	500
DSC-0002	FrameworkError	Server	500
DSC-0003	InvocationResultIncorrect	Server	500
DSC-0005	ServiceRuntimeException	Server	500
DSC-0006	SOAPDeserialisationFailure	Client	400
DSC-0007	XMLDeserialisationFailure	Client	400
DSC-0008	JSONDeserialisationParseFailure	Client	400
DSC-0009	ClassConversionFailure	Client	400	Invalid format for parameter, for example passing a string where a number was expected. Can also happen when a value is passed that does not match any valid enum.
DSC-0010	InvalidInputMediaType	Client	415
DSC-0011	ContentTypeNotValid	Client	415
DSC-0012	MediaTypeParseFailure	Client	415
DSC-0013	AcceptTypeNotValid	Client	406
DSC-0014	ResponseContentTypeNotValid	Server	500
DSC-0015	SecurityException	Client	403
DSC-0016	ServiceDisabled	Server	503
DSC-0017	OperationDisabled	Server	503
DSC-0018	MandatoryNotDefined	Client	400	A parameter marked as mandatory was not provided
DSC-0019	Timeout	Server	504
DSC-0020	BinDeserialisationParseFailure	Client	400
DSC-0021	NoSuchOperation	Client	404
DSC-0022	SubscriptionAlreadyActiveForEvent	Server	500
DSC-0023	NoSuchService	Client	404
DSC-0024	RescriptDeserialisationFailure	Client	400
DSC-0025	JMSTransportCommunicationFailure	Server	500
DSC-0026	RemoteCougarCommunicationFailure	Server	500
DSC-0027	OutputChannelClosedCantWrite	Server	?
DSC-0028	XMLSerialisationFailure	Server	500
DSC-0029	JSONSerialisationFailure	Server	500
DSC-0030	SOAPSerialisationFailure	Server	500
DSC-0031\	NoRequestsFound	Client\	400\
DSC-0032\	EPNSerialisationFailure	Server\	500\
DSC-0033\	UnidentifiedCaller	Client	400\
DSC-0034\	UnknownCaller	Client	400\
DSC-0035\	UnrecognisedCredentials	Client	400\
DSC-0036\	InvalidCredentials	Client	400\
DSC-0037\	SubscriptionRequired	Client	403\
DSC-0038\	OperationForbidden	Client	403\
DSC-0039\	NoLocationSupplied	Client\	400\
DSC-0040\	BannedLocation	Client\	403\

Service errorCodes

These are defined in the service BSIDLs, for example here we see that WEX-0001 indicates “The wotsit is closed”.

<interface name="Baseline" ...
    ...
    <exceptionType name="WotsitException" prefix="WEX">
        <description>This exception might be thrown when an operation fails</description>
        <parameter name="errorCode" type="string">
            <description>the unique code for this error</description>
        <validValues>
            <value id="1" name="CLOSED">
                <description>The wotsit is closed</description>
            </value>
                ...

Example faults

HTTP Transport, SOAP Protocol

A SOAP fault for a malformed request with detailed fault reporting switched on:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Header/>
   <soap:Body>
      <soap:Fault>
         <faultcode>soap:Client</faultcode>
         <faultstring>DSC-0006</faultstring>
         <detail>
            <trace/>
            <message>com.ctc.wstx.exc.WstxParsingException: Unexpected close tag &lt;/bas:TestExceptionRquest>; expected &lt;/bas:TestExceptionRequest>.
 at [row,col {unknown-source}]: [5,31]</message>
         </detail>
      </soap:Fault>
   </soap:Body>
</soap:Envelope>

A SOAP fault for a Null pointer exception being thrown in the application code with detailed fault reporting switched off:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="http://www.betfair.com/security/">
   <soap:Header/>
   <soap:Body>
      <soap:Fault>
         <faultcode>soap:Server</faultcode>
         <faultstring>DSC-0005</faultstring>
         <detail/>
      </soap:Fault>
   </soap:Body>
</soap:Envelope>

A SOAP fault for a defined exception (WotsitException) with 2 parameters (errorCode & type) being thrown and detailed fault reporting switched on

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sec="http://www.betfair.com/security/">
   <soap:Header/>
   <soap:Body>
      <soap:Fault>
         <faultcode>soap:Client</faultcode>
         <faultstring>WEX-0001</faultstring>
         <detail>
            <app:WotsitException xmlns:app="http://www.betfair.com/servicetypes/v1/Baseline/">
               <app:errorCode>CLOSED</app:errorCode>
               <app:type>SPICY</app:type>
            </app:WotsitException>
            <trace>com.betfair.baseline.v1_0.exception.WotsitException: WEX-0001
    at com.betfair.cougar.baseline.BaselineServiceImpl.testException(BaselineServiceImpl.java:189)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
    at java.lang.reflect.Method.invoke(Method.java:597)
    at com.betfair.cougar.core.impl.handler.OperationInvoker.handleInternal(OperationInvoker.java:45)
    at com.betfair.cougar.core.api.handler.InternalHandler.handle(InternalHandler.java:18)
    at com.betfair.cougar.core.impl.ChainImpl.execute(ChainImpl.java:53)
    at com.betfair.cougar.core.impl.server.CougarServer.service(CougarServer.java:128)
    at com.betfair.cougar.transport.http.jetty.JettyServiceHandler.handle(JettyServiceHandler.java:45)
    at org.mortbay.jetty.handler.HandlerList.handle(HandlerList.java:49)
    at org.mortbay.jetty.handler.HandlerCollection.handle(HandlerCollection.java:113)
    at org.mortbay.jetty.handler.HandlerWrapper.handle(HandlerWrapper.java:152)
    at org.mortbay.jetty.Server.handle(Server.java:324)
    at org.mortbay.jetty.HttpConnection.handleRequest(HttpConnection.java:550)
    at org.mortbay.jetty.HttpConnection$RequestHandler.content(HttpConnection.java:890)
    at org.mortbay.jetty.HttpParser.parseNext(HttpParser.java:743)
    at org.mortbay.jetty.HttpParser.parseAvailable(HttpParser.java:215)
    at org.mortbay.jetty.HttpConnection.handle(HttpConnection.java:407)
    at org.mortbay.io.nio.SelectChannelEndPoint.run(SelectChannelEndPoint.java:421)
    at org.mortbay.thread.QueuedThreadPool$PoolThread.run(QueuedThreadPool.java:520)</trace>
            <message>WotsitException</message>
         </detail>
      </soap:Fault>
   </soap:Body>
</soap:Envelope>

HTTP Transport, RESCRIPT Protocol, XML Content Type

A fault for an internal problem in the cougar code with detailed fault reporting switched on:

<fault>
   <faultcode>Server</faultcode>
   <faultstring>DSC-0002</faultstring>
   <detail>
      <trace/>
      <message>Unhandled event found in serialiser</message>
   </detail>
</fault>

HTTP Transport, RESCRIPT Protocol, JSON Content Type

An IDL defined exception (SimpleException with fields errorCode and reason) thrown by the application code:

{
   "detail":    {
      "message": "SimpleException",
      "trace": "com.betfair.baseline.v1_0.exception.SimpleException: SEX-0001\r\n\tat com.betfair.cougar.baseline.BaselineServiceImpl.testException(BaselineServiceImpl.java:179)\r\n\tat sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)\r\n\tat sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)\r\n\tat sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)\r\n\tat java.lang.reflect.Method.invoke(Method.java:597)\r\n\tat com.betfair.cougar.core.impl.handler.OperationInvoker.handleInternal(OperationInvoker.java:45)\r\n\tat com.betfair.cougar.core.api.handler.InternalHandler.handle(InternalHandler.java:18)\r\n\tat com.betfair.cougar.core.impl.ChainImpl.execute(ChainImpl.java:53)\r\n\tat com.betfair.cougar.core.impl.server.CougarServer.service(CougarServer.java:129)\r\n\tat com.betfair.cougar.transport.http.jetty.JettyServiceHandler.handle(JettyServiceHandler.java:45)\r\n\tat org.mortbay.jetty.handler.HandlerList.handle(HandlerList.java:49)\r\n\tat org.mortbay.jetty.handler.HandlerCollection.handle(HandlerCollection.java:113)\r\n\tat org.mortbay.jetty.handler.HandlerWrapper.handle(HandlerWrapper.java:152)\r\n\tat org.mortbay.jetty.Server.handle(Server.java:324)\r\n\tat org.mortbay.jetty.HttpConnection.handleRequest(HttpConnection.java:550)\r\n\tat org.mortbay.jetty.HttpConnection$RequestHandler.headerComplete(HttpConnection.java:876)\r\n\tat org.mortbay.jetty.HttpParser.parseNext(HttpParser.java:535)\r\n\tat org.mortbay.jetty.HttpParser.parseAvailable(HttpParser.java:209)\r\n\tat org.mortbay.jetty.HttpConnection.handle(HttpConnection.java:407)\r\n\tat org.mortbay.io.nio.SelectChannelEndPoint.run(SelectChannelEndPoint.java:421)\r\n\tat org.mortbay.thread.QueuedThreadPool$PoolThread.run(QueuedThreadPool.java:520)\r\n",
      "SimpleException":       {
         "reason": "GENERIC",
         "errorCode": "GENERIC"
      }
   },
   "faultcode": "Client",
   "faultstring": "SEX-0001"
}