Error handling

Each Client Lib function returns either ERROR_ok on success or an error value as defined in public_errors.h if the function fails.

The returned error codes are organized in groups, where the first byte defines the error group and the second the count within the group: The naming convention is ERROR_<group>_<error>, for example ERROR_client_invalid_id.


unsigned int error;
char* welcomeMsg;

error = ts3client_getServerVariableAsString(serverConnectionHandlerID,
if(error == ERROR_ok) {
    /* Use welcomeMsg... */
    ts3client_freeMemory(welcomeMsg);  /* Release memory *only* if function did not return an error */
} else {
    /* Handle error */
    /* Do not access or release welcomeMessage, the variable is undefined */

Client Lib functions returning C-strings or arrays dynamically allocate memory which has to be freed by the caller using ts3client_freeMemory. It is important to only access and release the memory if the function returned ERROR_ok. Should the function return an error, the result variable is uninitialized, so freeing or accessing it could crash the application.

See the section Calling Client Lib functions for additional notes and examples.

A printable error string for a specific error code can be queried with

unsigned int ts3client_getErrorMessage(errorCode,  
unsigned int errorCode;
char** error;


unsigned int error;
anyID myID;

error = ts3client_getClientID(scHandlerID, &myID);  /* Calling some Client Lib function */
if(error != ERROR_ok) {
    char* errorMsg;
    if(ts3client_getErrorMessage(error, &errorMsg) == ERROR_ok) {  /* Query printable error */
        printf("Error querying client ID: %s\n", errorMsg);
        ts3client_freeMemory(errorMsg);  /* Release memory */

In addition to actively querying errors like above, error codes can be sent by the server to the client. In that case the following event is called:

void onServerErrorEvent(serverConnectionHandlerID,  
uint64 serverConnectionHandlerID;
const char* errorMessage;
unsigned int error;
const char* returnCode;
const char* extraMessage;