Exception Class and Built-In Exceptions

An exception denotes an error that disrupts the normal flow of code execution. You can use Apex built-in exceptions or create custom exceptions. All exceptions have common methods.

All exceptions support built-in methods for returning the error message and exception type. In addition to the standard exception class, there are several different types of exceptions:

The following are exceptions in the System namespace.

Exception Description
AsyncException Any problem with an asynchronous operation, such as failing to enqueue an asynchronous call.
CalloutException Any problem with a Web service operation, such as failing to make a callout to an external system.
DmlException Any problem with a DML statement, such as an insert statement missing a required field on a record.
EmailException Any problem with email, such as failure to deliver. For more information, see Outbound Email.
InvalidParameterValueException An invalid parameter was supplied for a method or any problem with a URL used with Visualforce pages. For more information on Visualforce, see the Visualforce Developer's Guide.
JSONException Any problem with JSON serialization and deserialization operations. For more information, see the methods of System.JSON, System.JSONParser, and System.JSONGenerator.
ListException Any problem with a list, such as attempting to access an index that is out of bounds.
MathException Any problem with a mathematical operation, such as dividing by zero.
NoAccessException Any problem with unauthorized access, such as trying to access an sObject that the current user does not have access to. This is generally used with Visualforce pages. For more information on Visualforce, see the Visualforce Developer's Guide.
NoDataFoundException Any problem with data that does not exist, such as trying to access an sObject that has been deleted. This is generally used with Visualforce pages. For more information on Visualforce, see the Visualforce Developer's Guide.
NoSuchElementException Used specifically by the Iteratornext method. This exception is thrown if you try to access items beyond the end of the list. For example, if iterator.hasNext() == false and you call iterator.next(), this exception is thrown.
NullPointerException Any problem with dereferencing null, such as in the following code:
String s;
s.toLowerCase(); // Since s is null, this call causes
                 // a NullPointerException
QueryException Any problem with SOQL queries, such as assigning a query that returns no records or more than one record to a singleton sObject variable.
RequiredFeatureMissing A Chatter feature is required for code that has been deployed to an organization that does not have Chatter enabled.
SearchException Any problem with SOSL queries executed with SOAP APIsearch() call, for example, when the searchString parameter contains less than two characters. For more information, see the SOAP API Developer's Guide.
SecurityException Any problem with static methods in the Crypto utility class. For more information, see Crypto Class.
SerializationException Any problem with the serialization of data. This is generally used with Visualforce pages. For more information on Visualforce, see the Visualforce Developer's Guide.
SObjectException Any problem with sObject records, such as attempting to change a field in an update statement that can only be changed during insert.
StringException Any problem with Strings, such as a String that is exceeding your heap size.
TypeException Any problem with type conversions, such as attempting to convert the String 'a' to an Integer using the valueOf method.
VisualforceException Any problem with a Visualforce page. For more information on Visualforce, see the Visualforce Developer's Guide.
XmlException Any problem with the XmlStream classes, such as failing to read or write XML.

The following is an example using the DmlException exception:

Account[] accts = new Account[]{new Account(billingcity = 'San Jose')};
try {
    insert accts;
} catch (System.DmlException e) {
    for (Integer i = 0; i < e.getNumDml(); i++) {
        // Process exception here
        System.debug(e.getDmlMessage(i)); 
    }
}
For exceptions in other namespaces, see:

Common Exception Methods

Exception methods are all called by and operate on a particular instance of an exception. The table below describes all instance exception methods. All types of exceptions have the following methods in common:

Name Arguments Return Type Description
getCause Exception Returns the cause of the exception as an exception object.
getLineNumber Integer Returns the line number from where the exception was thrown.
getMessage String Returns the error message that displays for the user.
getStackTraceString String Returns the stack trace as a string.
getTypeName String Returns the type of exception, such as DmlException, ListException, MathException, and so on.
initCause Exception cause Void Sets the cause for this exception, if one has not already been set.
setMessage String s Void Sets the error message that displays for the user.

DMLException and EmailException Methods

In addition to the common exception methods, DMLExceptions and EmailExceptions have the following additional methods:

Name Arguments Return Type Description
getDmlFieldNames Integer i String [] Returns the names of the field or fields that caused the error described by the ith failed row.
getDmlFields Integer i Schema.sObjectField [] Returns the field token or tokens for the field or fields that caused the error described by the ith failed row. For more information on field tokens, see Dynamic Apex.
getDmlId Integer i String Returns the ID of the failed record that caused the error described by the ith failed row.
getDmlIndex Integer i Integer Returns the original row position of the ith failed row.
getDmlMessage Integer i String Returns the user message for the ith failed row.
getDmlStatusCode Integer i String Deprecated. Use getDmlType instead. Returns the Apex failure code for the ith failed row.
getDmlType Integer i System.StatusCode Returns the value of the System.StatusCode enum. For example:
try {
  insert new Account();
}   catch (System.DmlException ex) {
      System.assertEquals(
         StatusCode.REQUIRED_FIELD_MISSING,
         ex.getDmlType(0));
}

For more information about System.StatusCode, see Enums.

getNumDml Integer Returns the number of failed rows for DML exceptions.
© Copyright 2000–2014 salesforce.com, inc. All rights reserved.
Various trademarks held by their respective owners.