API Exceptions

Overview

Sugar comes with some predefined API Exceptions, located in ./include/api/, that can be called from API endpoints. These exceptions return a specific HTTP code and a message.

Stock Exceptions

Using Exceptions

When extending endpoints in Sugar, the stock API exceptions can be used to return errors and messages. The exception classes accept a single parameter on creation for the message value to return. This parameter can accept language label keys or plain text. If no parameter is passed exception, the error will default to the exception's default language label key. To call a stock API exception from custom code add the following snippet :

  //throwing an api exception using the stock message 
throw new SugarApiExceptionError();

//throwing an api exception using a custom language label key
throw new SugarApiExceptionError('EXCEPTION_CSTM_LABEL_KEY');

//throwing an api exception with text
throw new SugarApiExceptionError('There has been an error.');

This will return an http response code of 500 with the following response data:

  {
    "error": "fatal_error",
    "error_message": "There has been an error."
}

Custom Exceptions

Sugar gives you the ability to create custom API exceptions by creating a new class in ./custom/include/api/ that extends the stock SugarApiException class. When extending the class you can provide the following properties in your custom code:

Example

The following example will demonstrate how to create a custom exception.

./custom/include/api/<name>.php

  <?php

require_once 'include/api/SugarApiException.php';

/**
 * Custom error.
 */
class cstmSugarApiExceptionError extends SugarApiException
{
    public $httpCode = 404;
    public $errorLabel = 'my_error';
    public $messageLabel = 'EXCEPTION_CSTM_LABEL_KEY';
}

Create a custom language label using the extension framework:

./custom/Extension/application/Ext/Language/<name>.php

  <?php

$app_strings['EXCEPTION_CSTM_LABEL_KEY'] = 'My Exception Message.';

You can call your new exception by using the following code : 

  require_once 'custom/include/api/<name>.php';

//throwing custom api exception using the default message 
throw new cstmSugarApiExceptionError();

//throwing custom api exception using a custom language label key
throw new cstmSugarApiExceptionError('EXCEPTION_CSTM_LABEL_KEY');

//throwing custom api exception with text
throw new cstmSugarApiExceptionError('There has been an error.');

You will then need to navigate to Admin > Repair > Quick Repair and Rebuild before using your exception.

The exception error will return a response of: 

  {
    "error": "my_error",
    "error_message": "There has been an error."
}