Get Started Card Payments Check Payments Recurring Payments Gift & Loyalty Payments Fraud Plugins & Integrations Reporting Demo Heartland Pay App Other Solutions Fully Integrated POS Middleware Connectors Portico Gateway Documentation API Overview Gift & Loyalty Bill Pay Payroll Introduction Developer Support Authentication Credit Card Gift Card eCheck & ACH Recurring Reporting Error Handling Semi-Integrated Devices Heartland Profac Global Payments eCommerce Tokenization Demo Testing Knowledge Center GitHub Partnerships
Get sandbox account
Get sandbox account

Error Handling

Each Heartland SDK handles the following error types which all inherit from ApiException:

Error Type Meaning
BuilderException Handle builder validation issues
ConfigurationException Handle cases when the service or gateway is configured incorrectly
GatewayException Handle gateway-related exceptions: invalid cc number, gateway-timeout, etc
UnsupportedTransactionException Handle cases when the configured transaction isn’t supported by the gateway, payment method, etc.

Error Handler

# coming soon
from globalpayments.api.entities.exceptions import (
            ApiException, BuilderException, ConfigurationException,
            GatewayException, UnsupportedTransactionException)

try:
            response = card.charge(-5) \
            .with_currency('USD') \
            .with_address(address) \
            .execute()
except BuilderException as e:
            // handle error
except ConfigurationException as e:
            // handle error
except GatewayException as e:
            // handle error
except UnsupportedTransactionException as e:
            // handle error
except ApiException as e:
            // handle error
using GlobalPayments.Api.Entities;

try
{
            card.Charge(-5m)
            .WithCurrency("USD")
            .WithAddress(address)
            .Execute();
}
catch (BuilderException e)
{
            // handle error
}
catch (ConfigurationException e)
{
            // handle error
}
catch (GatewayException e)
{
            // handle error
}
catch (UnsupportedTransactionException e)
{
            // handle error
}
catch (ApiException e)
{
            // handle error
}
<?php
use GlobalPayments\Api\Entities\Exceptions\ApiException;
use GlobalPayments\Api\Entities\Exceptions\BuilderException;
use GlobalPayments\Api\Entities\Exceptions\ConfigurationException;
use GlobalPayments\Api\Entities\Exceptions\GatewayException;
use GlobalPayments\Api\Entities\Exceptions\UnsupportedTransactionException;

try
{
            $card->charge(-5)
            ->withCurrency("USD")
            ->withAddress($address)
            ->execute();
}
catch (BuilderException $e)
{
            // handle error
}
catch (ConfigurationException $e)
{
            // handle error
}
catch (GatewayException $e)
{
            // handle error
}
catch (UnsupportedTransactionException $e)
{
            // handle error
}
catch (ApiException $e)
{
            // handle error
}
import com.global.api.entities.exceptions.ApiException;
import com.global.api.entities.exceptions.BuilderException;
import com.global.api.entities.exceptions.ConfigurationException;
import com.global.api.entities.exceptions.GatewayException;
import com.global.api.entities.exceptions.UnsupportedTransactionException;
import java.math.BigDecimal;

try
{
            card.charge(new BigDecimal("-5"))
            .withCurrency("USD")
            .withAddress(address)
            .execute();
}
catch (BuilderException e)
{
            // handle error
}
catch (ConfigurationException e)
{
            // handle error
}
catch (GatewayException e)
{
            // handle error
}
catch (UnsupportedTransactionException e)
{
            // handle error
}
catch (ApiException e)
{
            // handle error
}
import {
            ApiError,
            BuilderError,
            ConfigurationError,
            GatewayError,
            UnsupportedTransactionError
} from "globalpayments-api";

card.charge(-5)
            .withCurrency("USD")
            .withAddress(address)
            .execute()
            .catch((e) => {
            switch (e.name) {
            case BuilderError.constructor.name:
            // handle error
            break;
            case ConfigurationError.constructor.name:
            // handle error
            break;
            case GatewayError.constructor.name:
            // handle error
            break;
            case UnsupportedTransactionError.constructor.name:
            // handle error
            break;
            case ApiError.constructor.name:
            default:
            // handle error
            break;
            }
            });
Heartland