Errors, Rate Limits & Usage

Every exception extends IpApiError, which carries $statusCode and the raw response $body. Catch the specific subclass you care about.

<?php

use IpApiIo\Client;
use IpApiIo\IpApiError;
use IpApiIo\AuthenticationError;
use IpApiIo\RateLimitError;
use IpApiIo\InvalidRequestError;
use IpApiIo\ServerError;

$client = new Client(apiKey: getenv('IP_API_IO_KEY'));

try {
    $info = $client->lookup('8.8.8.8');
    echo $info['location']['country'];
} catch (RateLimitError $e) {
    echo "quota hit — resets at {$e->reset}";
} catch (AuthenticationError $e) {
    echo 'check your API key';
} catch (InvalidRequestError $e) {
    echo 'bad request: ', $e->getMessage();
} catch (ServerError $e) {
    echo 'ip-api.io is having trouble, try later';
} catch (IpApiError $e) {
    echo "error {$e->statusCode}: ", $e->getMessage();
}

On HTTP 429 the client throws RateLimitError, parsed from the x-ratelimit-* headers. Because the client never retries, reset tells you when to.

try {
    $client->lookup('8.8.8.8');
} catch (RateLimitError $e) {
    echo $e->limit;      // your quota for the window
    echo $e->remaining;  // requests left (0 here)
    echo $e->reset;      // unix timestamp when quota renews
    $wait = $e->reset - time();
    // schedule a retry after $wait seconds instead of hammering the API
}

Read your current limits without triggering a 429, so you can throttle in advance.

$rl = $client->rateLimit();

echo $rl['plan_name'];
echo $rl['ip_api']['remaining'], ' / ', $rl['ip_api']['limit'];
echo $rl['email_api']['usage_percent'], '% used';
echo $rl['next_renewal_date'];

Aggregate usage for the current period — handy for dashboards and internal alerts.

$usage = $client->usageSummary();

echo $usage['totalRequests'], ' ', $usage['successfulRequests'];
echo $usage['rateLimitedRequests'], ' ', $usage['quotaConsumed'];
echo $usage['periodStart'], ' -> ', $usage['periodEnd'];