Exceptions

Provider error responses and unreachable APIs never abort a lookup — they count as a miss and the pipeline moves on. The package throws for configuration problems (an unknown provider, a missing or corrupt MaxMind database), invalid input, a failed database refresh and the opt-in rate-limit ceiling. Every exception lives in RoundlyConsulting\Geolocation\Exceptions:

A malformed config value — a typo’d switch, a non-integer timeout, an unknown rate-limit window — throws package-toolkit’s RoundlyConsulting\PackageToolkit\Exceptions\InvalidConfigurationException naming the key instead. It is not a GeolocationException, so catching GeolocationException never hides a misconfiguration.

Connection failures

When a provider can’t be reached at all — a timeout, a DNS failure, a refused connection — Laravel’s HTTP client retries per the provider’s retry settings, then the provider throws ProviderUnavailableException and the manager skips to the next provider. If nothing answers, the lookup returns null and LocationResolutionFailed names the last unreachable provider and its error. distance() skips an unreachable provider the same way, and distanceMatrix() degrades every cell to null.

API keys and the MaxMind license key never appear in exception messages: they are redacted, and the transport exception — whose message quotes the full request URL — is not chained as previous.

Catch GeolocationException to handle everything in one place:

use RoundlyConsulting\Geolocation\Exceptions\GeolocationException;

try {
    $location = Geolocation::locateRequest();
} catch (GeolocationException $e) {
    report($e);   // missing or corrupt .mmdb, rate-limit ceiling, unknown provider...
    $location = null;
}

batch() already catches per item and turns any exception into null for that IP.