Exceptions

Every exception extends ImportsException (a RuntimeException). HTTP-aware ones implement Symfony’s HttpExceptionInterface, so Laravel’s handler answers with their status and translated message ({"message": …}) — no global rendering is registered:

use RoundlyConsulting\Imports\Exceptions\{ImportAlreadyRunningException, ImportsException};

try {
    $batch = Imports::for($team)->by($user)->session($id)->commit();
} catch (ImportAlreadyRunningException $e) {
    $e->runningSessionId;    // the session that holds the lock
} catch (ImportsException $e) {
    // the base class — HTTP-aware ones render as {"message": …} with their status by themselves
}

ImportRowException is yours to throw from a callback. UnscopedQueryException and InvalidImporterDefinitionException signal an importer that breaks a rule; InvalidImportsConfigurationException names the config key at fault.