When using brainCloud, your app will need to handle certain error conditions. There are two main types of errors that can occur while using the brainCloud client library:
- Network errors – A network error indicates that a packet was sent to brainCloud but no response was received.
- API call errors – A packet was sent to (and received by) brainCloud but resulted in a non-200 HTTP response
In order to effectively respond to these error conditions, developers need to implement error handlers. A list of error reason codes returned by brainCloud can be found here:
Below are the specifics for implementing error handlers for the various supported brainCloud client platforms.
Unity/C# library
All API calls have two callback delegates as parameters, one for success and one for failure:
/// <summary> /// Success callback for an API method. /// </summary> /// <param name="jsonResponse">The json response from the server</param> /// <param name="cbObject">The user supplied callback object</param> public delegate void SuccessCallback(string jsonResponse, object cbObject); /// <summary> /// Failure callback for an API method. /// </summary> /// <param name="status">The http status code</param> /// <param name="reasonCode">The error reason code</param> /// <param name="jsonError">The error json string</param> /// <param name="cbObject">The user supplied callback object</param> public delegate void FailureCallback(int status, int reasonCode, string jsonError, object cbObject)
For example, the AuthenticateUniversal method is defined as follows:
public void AuthenticateUniversal(string userid, string password, bool forceCreate, SuccessCallback success, FailureCallback failure);
If authentication succeeds, the success callback function will be called with the json response from brainCloud. The user-supplied callback object will also be returned (in case you need to keep track of some contextual information).
If authentication fails, the HTTP status code, a reason code, and a json response describing the error will be returned. In order to handle the error effectively, you can refer to the Reason Code Appendix.
C++ library
The C++ library has a slightly different mechanism for dealing with callbacks. Specifically, all API methods take in an “IServerCallback” pointer. This interface declares the following methods:
/** * The serverCallback() method returns server data back to the layer * interfacing with the BrainCloud library. * * @param serviceName - name of the requested service * @param serviceOperation - requested operation * @param jsonData - returned data from the server */ virtual void serverCallback( ServiceName serviceName, ServiceOperation serviceOperation, std::string const & jsonData) = 0; /** * Errors are returned back to the layer which is interfacing with the * BrainCloud library through the serverError() callback. * * A server error might indicate a failure of the client to communicate * with the server after N retries. * * @param serviceName The service name being called * @param serviceOperation The service operation being called * @param statusCode The error status return code (400, 403, 500, etc) * @param reasonCode The brainCloud reason code (see reason codes on apidocs site) * @param jsonError The error json string */ virtual void serverError( ServiceName serviceName, ServiceOperation serviceOperation, int statusCode, int reasonCode, const std::string & jsonError) = 0;
For example, the AuthenticateUniversal method is defined as follows:
void authenticateUniversal(const char * in_userid, const char * in_password, bool in_forceCreate, IServerCallback * in_callback);
Java library
The Java library is similar to C++ in that there is an IServerCallback interface that can be supplied to any API call. This interface declares the following methods:
public interface IServerCallback { /** * The serverCallback() method returns server data back to the layer * interfacing with the BrainCloud library. * * @param serviceName - name of the requested service * @param serviceOperation - requested operation * @param jsonData - returned data from the server */ void serverCallback(ServiceName serviceName, ServiceOperation serviceOperation, JSONObject jsonData); /** * Errors are returned back to the layer which is interfacing with the * BrainCloud library through the serverError() callback. * * A server error might indicate a failure of the client to communicate * with the server after N retries. * * @param statusCode The error status return code (400, 403, 500, etc) * @param reasonCode The brainCloud reason code (see reason codes on apidocs site) * @param jsonError The error json string */ void serverError(int statusCode, int reasonCode, String jsonError); }
For example, the AuthenticateUniversal method is defined as follows:
public void authenticateUniversal(String userId, String userPassword, boolean forceCreate, IServerCallback callback);
Javascript library
Coming soon!
Cloud Code
See Cloud Code section in API modules