Error Handling & Retries

The coinglass-go SDK is designed to be resilient and provides detailed error information to help you build robust applications.

API Errors

Any non-2xx response, or a response whose Coinglass envelope code isn't "0", comes back as an *coinglass.APIError.

type APIError struct {
    StatusCode int
    Code       string
    Message    string
    RawBody    []byte
}

Sentinel Errors

For common HTTP status codes, the SDK provides sentinel errors that you can check using errors.Is:

• coinglass.ErrUnauthorized (HTTP 401) - Check your API key.
• coinglass.ErrNotFound (HTTP 404) - Resource not found.
• coinglass.ErrRateLimited (HTTP 429) - Rate limit exceeded (returned if retries are disabled or exhausted).

Inspecting Errors

You can use errors.Is for simple checks, and errors.As when you need the full APIError details:

import "errors"

oi, err := client.Futures.OpenInterestHistory(ctx, params)
if err != nil {
    switch {
    case errors.Is(err, coinglass.ErrUnauthorized):
        log.Fatal("Invalid API key")
    case errors.Is(err, coinglass.ErrRateLimited):
        log.Println("Rate limited — retries exhausted")
    default:
        var apiErr *coinglass.APIError
        if errors.As(err, &apiErr) {
            log.Printf("API error %d (%s): %s", apiErr.StatusCode, apiErr.Code, apiErr.Message)
            // You can also inspect apiErr.RawBody if needed
        } else {
            log.Printf("Network or other error: %v", err)
        }
    }
}

Automatic Retries

The Coinglass API enforces rate limits (e.g., 30 requests/min for the Hobbyist plan). The SDK can automatically retry requests that fail with an HTTP 429 Too Many Requests status.

By default, retries are disabled (max attempts = 1). It is strongly recommended to enable them for production workloads.

Enabling Retries

Use the WithRetry option when creating the client. You specify the maximum number of attempts (including the initial request) and the base delay.

// 3 attempts total. Initial backoff is 1 second.
client := coinglass.NewClient("YOUR_API_KEY",
    coinglass.WithRetry(3, 1 * time.Second),
)

Backoff Strategy

1. If the API sends a Retry-After header, the SDK will wait for that exact number of seconds.
2. Otherwise, it uses exponential backoff. If baseDelay is 1s, the delays between attempts will be 1s, 2s, 4s, etc.
3. If the context passed to the method is canceled or times out during a backoff sleep, the retry loop aborts immediately and returns the context error.