Skip to main content

Troubleshooting

Quick solutions to common issues with the Axol API.

Authentication Issues​

Error: "Invalid API key"​

Problem: Your API key is not recognized.

Solutions:

  1. Verify the key is correct (check for extra spaces)
  2. Ensure key hasn't been revoked in dashboard
  3. Check you're using the right environment (production vs test)

Test your key:

curl https://api.axol.io/api/v1/health \
  -H "X-API-Key: YOUR_KEY"

Error: "Insufficient permissions"​

Problem: API key lacks required scope.

Solutions:

  1. Check key scopes in dashboard
  2. Create new key with required permissions
  3. Use different key for admin operations

Rate Limiting​

Error: 429 Too Many Requests​

Problem: Exceeded throughput limit (CUPs).

Solutions:

  1. Implement exponential backoff:
import time

def with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except RateLimitError as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)
  1. Reduce request rate
  2. Upgrade to higher tier for more CUPs

Error: 402 CU Pool Exhausted​

Problem: Used all monthly CUs.

Solutions:

  1. Wait until billing cycle resets (check X-RateLimit-CU-Reset header)
  2. Enable overage billing in dashboard
  3. Upgrade to higher tier
  4. Optimize usage (see Performance Issues section below)

Connection Issues​

Timeouts​

Problem: Requests timing out.

Solutions:

  1. Check status.axol.io for incidents
  2. Increase client timeout (default is often too low)
  3. Use retry logic with exponential backoff
  4. For trace methods, expect longer response times (up to 30s)
# Increase timeout for trace methods
client = AxolClient(api_key="KEY", timeout=60)

WebSocket Disconnections​

Problem: WebSocket connection drops.

Solutions:

  1. Implement auto-reconnect logic
  2. Send periodic heartbeats (ping/pong)
  3. Handle reconnection gracefully:
ws = AxolWebSocket(
    api_key="KEY",
    auto_reconnect=True,
    max_reconnect_attempts=5
)

Data Issues​

Stale Data​

Problem: Receiving outdated blockchain data.

Solutions:

  1. Use latest instead of specific block numbers when possible
  2. Check block timestamp in response
  3. Verify you're not hitting cached data (most queries are real-time)

Missing Historical Data​

Problem: Archive data not available.

Solutions:

  1. Check tier's data retention period:
    • Free/Starter: 30 days
    • Base: 90 days
    • Growth: 180 days
    • Scale+: Full history
  2. Upgrade tier for longer history
  3. For beta chains, expect limited archive data

Incorrect Chain Data​

Problem: Getting data from wrong chain.

Solutions:

  1. Verify chain identifier is correct (see Supported Chains)
  2. Check chain ID in response matches expected
  3. For multi-chain queries, verify request format

Performance Issues​

Slow Responses​

Problem: API calls taking too long.

Solutions:

  1. Trace methods are slow by design (1-30 seconds)
  2. Reduce block range for eth_getLogs queries
  3. Use batch endpoints when making multiple calls
  4. Cache responses when data is static (past blocks)
  5. Check your network latency to our servers

High CU Usage​

Problem: Consuming CUs faster than expected.

Solutions:

  1. Review method distribution in dashboard
  2. Avoid trace methods when not necessary
  3. Use narrow block ranges for log queries
  4. Cache results for static data
  5. See Compute Units for method cost details

SDK Issues​

Import Errors (Python)​

Problem: Can't import axol module.

Solutions:

# Reinstall SDK
pip uninstall axol-api-client
pip install axol-api-client

# Verify installation
python -c "import axol; print(axol.__version__)"

Type Errors (TypeScript)​

Problem: TypeScript compilation errors.

Solutions:

# Update SDK
npm update @axol/api-client

# Ensure proper types
npm install --save-dev @types/node

Getting Help​

Before Contacting Support​

  1. Check status page: status.axol.io
  2. Review logs: Look for error messages in responses
  3. Test with curl: Isolate if issue is SDK-specific
  4. Check tier limits: Verify you're within your plan's limits

Contact Support​

Include in support requests:

  • API key (last 8 characters only)
  • Request ID from error response
  • Timestamp of issue
  • Example request that reproduces the problem
  • Response received (including headers)

Common Questions​

Q: Why is my free tier exhausted so quickly? A: Check your method distribution. A few trace method calls can consume as much as millions of standard calls. See CU costs.

Q: Can I get a refund for unused CUs? A: CU pools reset monthly and don't roll over. Consider downgrading tier if consistently under-utilizing.

Q: How do I migrate from another provider? A: See chain identifier mapping in Supported Chains. Most RPC methods are standard across providers.

Q: Do you support testnets? A: Currently mainnet only. Contact hello@axol.io to express interest in testnet support.

See also: