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