Let the platform do the work

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

Exception Class HTTP Code Error Label Language Label Key Language Label Value
SugarApiExceptionError 500  fatal_error  EXCEPTION_FATAL_ERROR  Your request failed to complete. A fatal error occurred. Check logs for more details.
SugarApiExceptionIncorrectVersion 301 incorrect_version EXCEPTION_INCORRECT_VERSION  The version of the API you are using is not correct for the current request.
SugarApiExceptionNeedLogin 401 need_login EXCEPTION_NEED_LOGIN  You need to be logged in to perform this action.
SugarApiExceptionInvalidGrant 401 invalid_grant EXCEPTION_INVALID_TOKEN  Your authentication token is invalid.
SugarApiExceptionNotAuthorized 403 not_authorized EXCEPTION_NOT_AUTHORIZED You are not authorized to perform this action. Contact your administrator if you need access.
SugarApiExceptionPortalUserInactive 403 inactive_portal_user EXCEPTION_INACTIVE_PORTAL_USER  You cannot access Portal because your portal account is inactive. Please contact customer support if you need access.
SugarApiExceptionPortalNotConfigured 403 portal_not_configured EXCEPTION_PORTAL_NOT_CONFIGURED  Portal is not configured properly. Contact your Portal Administrator for assistance.
SugarApiExceptionNoMethod 404 no_method EXCEPTION_NO_METHOD  Your request was not supported. Could not find the HTTP method of your request for this path.
SugarApiExceptionNotFound 404 not_found EXCEPTION_NOT_FOUND  Your requested resource was not found. Could not find a handler for the path specified in the request.
SugarApiExceptionEditConflict 409 edit_conflict EXCEPTION_EDIT_CONFLICT  Edit conflict, please reload the record data.
SugarApiExceptionInvalidHash 412 metadata_out_of_date EXCEPTION_METADATA_OUT_OF_DATE Your metadata or user hash did not match the server. Please resync your metadata.
SugarApiExceptionRequestTooLarge 413 request_too_large EXCEPTION_REQUEST_TOO_LARGE Your request is too large to process.
SugarApiExceptionMissingParameter 422 missing_parameter EXCEPTION_MISSING_PARAMTER A required parameter in your request was missing.
SugarApiExceptionInvalidParameter 422 invalid_parameter EXCEPTION_INVALID_PARAMETER A parameter in your request was invalid.
SugarApiExceptionRequestMethodFailure 424 request_failure EXCEPTION_REQUEST_FAILURE Your request failed to complete.
SugarApiExceptionClientOutdated 433 client_outdated EXCEPTION_CLIENT_OUTDATED Your software is out of date, please update your client before attempting to connect again.
SugarApiExceptionConnectorResponse 502 bad_gateway EXCEPTION_CONNECTOR_RESPONSE A connector or an integration request resulted in a failed response.
SugarApiExceptionMaintenance 503 maintenance EXCEPTION_MAINTENANCE SugarCRM is in maintenance mode. Only admins can login. Please contact your administrator for details.
SugarApiExceptionServiceUnavailable 503 service_unavailable EXCEPTION_SERVICE_UNAVAILABLE The server cannot process your request because it is busy or unavailable at this time.
SugarApiExceptionSearchUnavailable 400 search_unavailable EXCEPTION_SEARCH_UNAVAILABLE Search engine is temporarily unavailable.
SugarApiExceptionSearchRuntime 400 search_runtime EXCEPTION_SEARCH_RUNTIME  A search engine runtime error occurred. Please contact your System Administrator.

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:

$httpCode The http response code to send back in the header. Defaults to 400 if not specified.
$errorLabel The string value returned in the 'error' key response.
$messageLabel The label to return as a default response if a message is not provided.

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."
}

Topics