Error Handling

The coinglass-php SDK provides a clear and predictable exception hierarchy for handling API errors. All exceptions extend a single base class, making it easy to write both granular and broad error-handling logic. The SDK also includes built-in retry logic for rate-limited responses.

Exception Hierarchy

Every exception thrown by the SDK extends Tigusigalpa\CoinGlass\Exceptions\CoinGlassException, which itself extends PHP's standard RuntimeException. This hierarchy allows you to catch any SDK error with a single type while still being able to handle specific cases individually.

RuntimeException
└── CoinGlassException
    ├── ApiException
    │   ├── UnauthorizedException  (HTTP 401)
    │   ├── NotFoundException      (HTTP 404)
    │   └── RateLimitException     (HTTP 429, after retries exhausted)
    └── WebSocketException

The table below describes each exception class.

Exception Class	HTTP Status	When It Is Thrown
CoinGlassException	—	Base class. Catch this to handle any SDK error.
ApiException	Any non-2xx	Non-2xx HTTP response, or a 2xx response with a non-zero envelope code.
UnauthorizedException	401	The API key is missing, invalid, or revoked.
NotFoundException	404	The requested endpoint or resource does not exist.
RateLimitException	429	The rate limit was exceeded and all retry attempts were exhausted.
WebSocketException	—	Connection, handshake, or read/write failure in the WebSocket client.

Handling Exceptions

The recommended pattern is to catch the most specific exceptions first, then fall back to the generic ApiException for anything else.

use Tigusigalpa\CoinGlass\Exceptions\ApiException;
use Tigusigalpa\CoinGlass\Exceptions\NotFoundException;
use Tigusigalpa\CoinGlass\Exceptions\RateLimitException;
use Tigusigalpa\CoinGlass\Exceptions\UnauthorizedException;

try {
    $oi = $client->futures()->openInterestOhlcHistory('BTC', '1d', 30);
} catch (UnauthorizedException $e) {
    // The API key is invalid or missing.
    error_log("Authentication failed: " . $e->getMessage());
} catch (RateLimitException $e) {
    // All retry attempts were exhausted.
    // $e->retryAfter holds the Retry-After header value (in seconds), if provided.
    error_log("Rate limit hit. Retry after: " . ($e->retryAfter ?? 'unknown') . "s");
} catch (NotFoundException $e) {
    // The endpoint or resource was not found.
} catch (ApiException $e) {
    // Any other API error.
    // $e->statusCode   — the HTTP status code
    // $e->apiCode      — the Coinglass envelope 'code' field, if present
    // $e->responseBody — the decoded JSON response body
    error_log("API Error [HTTP {$e->statusCode}]: " . $e->getMessage());
}

Automatic Retries

The Coinglass API enforces rate limits and responds with HTTP 429 when they are exceeded. The CoinGlassClient handles this automatically using an exponential backoff strategy, so transient rate-limit errors are resolved without any additional code in your application.

How the Retry Logic Works

When the client receives a 429 response, it checks for a Retry-After header. If the header is present, the client waits for exactly that many seconds before retrying. If the header is absent, it falls back to exponential backoff: the wait time is retryDelay × 2^(attempt - 1). With the default configuration of retryDelay = 1.0 and retryAttempts = 3, the delays are 1 second, 2 seconds, and 4 seconds. If the client exhausts all configured attempts and still receives a 429, it throws a RateLimitException.

Configuring the Retry Policy

The retry policy is configured on CoinGlassConfig. The two relevant parameters are retryAttempts (the maximum number of retries) and retryDelay (the base delay in seconds for the exponential backoff).

use Tigusigalpa\CoinGlass\CoinGlassConfig;

$config = new CoinGlassConfig(
    apiKey: 'YOUR_API_KEY',
    retryAttempts: 5,   // Try up to 5 times
    retryDelay: 2.0,    // 2s, then 4s, then 8s, then 16s, then 32s
);

In a Laravel application, set these values in your .env file:

COINGLASS_RETRY_ATTEMPTS=5
COINGLASS_RETRY_DELAY=2

To disable automatic retries entirely, set retryAttempts to 0.

---

Next: Full API Reference