Skip to content

Troubleshooting Guide

This guide helps you troubleshoot common issues when using the Astral API.

Common API Errors

1. Unable to Connect to the API

Symptoms: - Request timeout - Connection refused - Unable to resolve host

Possible Causes: - API service may be down - Network connectivity issues - Incorrect API URL

Solutions: - Check the API status at https://api.astral.global/health - Verify your internet connection - Ensure you're using the correct API URL - Try again later if the service is experiencing downtime

2. 404 Not Found Errors

Symptoms: - Response with status code 404 - Error message: Cannot GET /path

Possible Causes: - Incorrect endpoint URL - Endpoint does not exist - API version mismatch

Solutions: - Double-check the endpoint URL in the API Reference - Ensure you're using the correct API version (v0) - Check for typos in the URL path

Example of a correct endpoint: 

https://api.astral.global/api/v0/location-proofs

3. 400 Bad Request Errors

Symptoms: - Response with status code 400 - Error message related to invalid parameters

Possible Causes: - Invalid query parameters - Malformed request body - Missing required parameters

Solutions: - Check the API documentation for required and optional parameters - Ensure query parameters have the correct format - Validate any JSON in the request body

Common parameter format issues: - Bounding box (bbox) should be an array of 4 numbers: [minLng, minLat, maxLng, maxLat] - Timestamps should be in ISO 8601 format: 2023-01-01T12:00:00Z - Ethereum addresses should include the 0x prefix

4. 429 Too Many Requests

Symptoms: - Response with status code 429 - "Too many requests" error message

Possible Causes: - Exceeded rate limits - Too many requests in a short period

Solutions: - Implement exponential backoff and retry logic - Reduce request frequency - Batch requests where possible

Example retry logic: 

async function fetchWithRetry(url, options = {}, maxRetries = 3) {
  let retries = 0;

  while (retries < maxRetries) {
    try {
      const response = await fetch(url, options);

      if (response.status === 429) {
        // Get retry-after header or use exponential backoff
        const retryAfter = response.headers.get('retry-after') || Math.pow(2, retries) * 1000;
        console.log(`Rate limited. Retrying after ${retryAfter}ms`);
        await new Promise(resolve => setTimeout(resolve, retryAfter));
        retries++;
        continue;
      }

      return response;
    } catch (error) {
      retries++;
      if (retries >= maxRetries) throw error;

      const delay = Math.pow(2, retries) * 1000;
      console.log(`Request failed, retrying in ${delay}ms...`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

5. 500 Internal Server Error

Symptoms: - Response with status code 500 - Generic server error message

Possible Causes: - Server-side issue - Database connection problems - Blockchain network issues

Solutions: - Check the API status - Retry the request after a short delay - Report the issue if it persists

1. Missing Location Proofs

Symptoms: - Empty results when querying location proofs - Fewer results than expected

Possible Causes: - No data matching the query parameters - Sync process not completed - Recent attestations not yet indexed

Solutions: - Check the sync status: GET /api/sync/status - Broaden your query parameters - Verify attestations exist on the blockchain - Wait for the next sync cycle to complete

2. Incorrect Coordinates

Symptoms: - Location proofs have unexpected coordinates - Points appear in the wrong places on a map

Possible Causes: - Coordinate order confusion (lat/lng vs lng/lat) - Different coordinate reference system - Data parsing issues

Solutions: - Note that GeoJSON uses longitude, latitude order: [lng, lat] - Check the srs field to determine the coordinate reference system - Verify the location data in the original attestation

3. Missing or Invalid Geographic Data

Symptoms: - null values for longitude or latitude - Cannot perform spatial queries

Possible Causes: - Original attestation missing geographic data - Malformed location data in attestation - Parsing errors during indexing

Solutions: - Check if the original attestation contains valid location data - Use the location field which contains the raw GeoJSON - Filter out proofs with missing coordinates: ?filter=hasCoordinates

API Integration Issues

1. CORS Errors

Symptoms: - Browser console errors about CORS policy - Unable to access API from frontend applications

Possible Causes: - Cross-Origin Resource Sharing restrictions - Missing CORS headers

Solutions: - Use a CORS proxy for development - Implement a backend API service to make requests - Request CORS support from the API provider

2. Performance Issues

Symptoms: - Slow API responses - Timeouts on large queries

Possible Causes: - Large result sets - Complex spatial queries - Network latency

Solutions: - Use pagination with limit and offset parameters - Add more specific filters to narrow results - Use the bbox parameter to limit geographic area - Implement caching for frequent queries

Example pagination: 

async function getAllLocationProofs() {
  const results = [];
  let offset = 0;
  const limit = 100;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(`https://api.astral.global/api/v0/location-proofs?limit=${limit}&offset=${offset}`);
    const data = await response.json();

    results.push(...data.data);

    if (data.data.length < limit) {
      hasMore = false;
    } else {
      offset += limit;
    }
  }

  return results;
}

3. Data Format Inconsistencies

Symptoms: - Unexpected data structure - Missing fields - Type errors in application code

Possible Causes: - API changes - Different data sources - Optional fields that are sometimes null

Solutions: - Implement defensive parsing with fallbacks - Validate API responses before processing - Use TypeScript or JSON Schema to define expected structures

Example defensive parsing: 

function parseLocationProof(proof) {
  return {
    id: proof.uid || '',
    chain: proof.chain || 'unknown',
    location: {
      latitude: proof.latitude || null,
      longitude: proof.longitude || null,
      type: proof.location_type || 'unknown'
    },
    timestamp: proof.event_timestamp ? new Date(proof.event_timestamp) : null,
    prover: proof.prover || '',
    // Always provide fallbacks for optional fields
  };
}

Blockchain-Specific Issues

1. Chain Sync Delays

Symptoms: - Recently created attestations not appearing - Missing data for specific chains

Possible Causes: - Sync process delay - Blockchain network issues - EAS indexer delays

Solutions: - Check sync status for specific chains - Trigger a manual sync: POST /api/sync?chain=sepolia - Wait for the next automatic sync cycle

2. Revoked Attestations

Symptoms: - Attestations marked as revoked - Data no longer accessible

Possible Causes: - Attestation revoked by the original attester - Fraudulent or erroneous attestation

Solutions: - Check revocation status: GET /api/v0/location-proofs/:uid - Include or exclude revoked attestations with the includeRevoked parameter - Verify revocation status on the blockchain

Sync Issues

1. Automatic Sync Not Working

Symptoms: - New attestations not appearing in the API - Status endpoint shows no recent syncs

Possible Causes: - Cron job issues - Service configuration problems - Database connection issues

Solutions: - Check sync status: GET /api/sync/status - Manually trigger a sync: POST /api/cron/sync - Test endpoint availability: GET /api/cron/sync/test - Wait for the automatic sync (runs every minute)

2. Revocation Checks Not Updated

Symptoms: - Revoked attestations still show as valid - Revocation status isn't current

Possible Causes: - Revocation checking temporarily disabled - Sync job not completing fully

Solutions: - Check the API status for information about revocation checking - Manually check revocation status on-chain - Wait for the next sync cycle when revocation checks are enabled

Reporting Issues

If you encounter persistent issues that aren't covered in this guide:

  1. Check if the issue is already reported in the GitHub issues
  2. Create a new issue with:
  3. Detailed description of the problem
  4. Steps to reproduce
  5. API endpoint and parameters used
  6. Error messages and response codes
  7. Your environment (browser, OS, etc.)
  8. For urgent issues, contact the team through official support channels

API Status

You can check the current API status at: 

GET https://api.astral.global/health

For more detailed status information, including sync status: 

GET https://api.astral.global/api/sync/status

To verify the cron endpoint is correctly configured: 

GET https://api.astral.global/api/cron/sync/test