FAQ & Troubleshooting

Frequently asked questions and solutions to common issues when using the HDA API.

Note

For general DestinE Data Lake questions, see the FAQs section.

General Questions

Q: Do I need an account to use the HDA API?

  • Service discovery: No authentication required

  • Dataset discovery: No authentication required

  • Data access: DestinE account required

  • Account creation: Free at the DestinE Platform

Q: What’s the difference between STAC API v1 and v2?

STAC API v2 is the recommended interface with:

  • Enhanced ECMWF integration and ordering workflows

  • Direct data access endpoints (/data)

  • Improved performance and consistency

  • Better error handling and response formats

STAC API v1 is deprecated and will be discontinued in future releases.

Q: How much data can I download?

Default quotas for all users:

  • 4 requests/second rate limit

  • 20 Mbps bandwidth per connection

  • 6 TB/month data transfer

Extended quotas available through My DataLake Services.

Authentication Issues

Q: I get “401 Unauthorized” errors

Solution Steps

  1. Verify credentials - Check username/password

  2. Check token expiration - Tokens expire after ~10 hour

  3. Refresh token - Get a new access token

  4. Account status - Ensure account is active

# Check if token is expired
# please install the `PyJWT` library first
# pip install PyJWT
import jwt
import time

try:
    decoded = jwt.decode(token, options={"verify_signature": False})
    exp_time = decoded.get('exp', 0)
    if time.time() > exp_time:
        print("Token expired - refresh needed")
    else:
        print("Token is valid")
except:
    print("Invalid token format")

Q: Authentication works but data requests fail

Possible Causes

  • Missing Bearer prefix: Ensure header is Authorization: Bearer TOKEN

  • Token in wrong header: Some tools expect different header formats

  • Network issues: Check connectivity to hda.data.destination-earth.eu

  • Account permissions: Verify access to specific datasets

Q: How long do access tokens last?

Access tokens typically expire after 10 hours. Implement token refresh logic for long-running applications.

Data Discovery Issues

Q: I can’t find a specific dataset

Search Tips

  1. List all collections first to see what’s available

  2. Check collection IDs - they may differ from display names

  3. Use freetext search with dataset keywords

  4. Check spatial/temporal availability - not all datasets cover all areas/times

# Use freetext search on collections
# please install the `requests` library first
# pip install requests
import requests

collections_url = "https://hda.data.destination-earth.eu/stac/v2/collections?q=sentinel"
response = requests.get(collections_url)
collections = response.json().get('collections', [])

print(f"Found {len(collections)} collections matching 'sentinel'")
for collection in collections:
    print(f"{collection['id']}: {collection['title']}")

Q: Search returns no results

Common Issues

  • Bbox format: Use [west, south, east, north] order

  • Date format: Use ISO 8601 format YYYY-MM-DDTHH:MM:SSZ

  • Collection availability: Check if collection has data for your area/time

  • Coordinate system: Use WGS84 (EPSG:4326) coordinates

# Correct search example
search_params = {
    "collections": ["EO.ESA.DAT.SENTINEL-2.MSI.L2A"],
    "bbox": [2.2, 48.8, 2.4, 49.0],  # Paris: [west, south, east, north]
    "datetime": "2024-07-01T00:00:00Z/2024-07-31T23:59:59Z",
    "limit": 10
}

Q: How do I search by metadata properties?

Use the query parameter for property-based filtering:

search_params = {
    "collections": ["EO.ESA.DAT.SENTINEL-2.MSI.L2A"],
    "query": {
        "eo:cloud_cover": {"lte": 20}  # Less than 20% cloud cover
    }
}

Data Access Issues

Q: Downloads are very slow

Optimization Tips

  1. Check bandwidth quotas - you may be rate limited

Q: “403 Forbidden” when accessing data

Possible Causes

  • Quota exceeded: Check your monthly transfer limit

  • Dataset restrictions: Some datasets require special permissions

Q: Files are corrupted or incomplete

Troubleshooting

  1. Check HTTP response status during download

  2. Verify file size matches expected size

  3. Retry failed downloads with proper error handling

Performance Issues

Q: API responses are slow

Performance Tips

  • Use appropriate page sizes - don’t request too many items at once

  • Filter searches to reduce response size

Q: I’m hitting rate limits

Rate Limit Strategies

  1. Monitor your request rate - stay under 4 requests/second

  2. Request extended quotas for production workloads

  3. Implement exponential backoff when you get 429 errors

import time
import random

def make_request_with_backoff(url, headers, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.get(url, headers=headers)
            if response.status_code == 429:  # Rate limited
                wait_time = (2 ** attempt) + random.uniform(0, 1)
                print(f"Rate limited, waiting {wait_time:.1f}s...")
                time.sleep(wait_time)
                continue
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(1)

Error Codes Reference

Code

Meaning

Solution

400

Bad Request

Check request parameters, format, and syntax

401

Unauthorized

Verify authentication token and credentials

403

Forbidden

Check quotas, permissions, and dataset access rights

404

Not Found

Verify collection/item IDs and endpoint URLs

422

Unprocessable Entity

Check parameter values and data format

429

Too Many Requests

Implement rate limiting and backoff strategies

500

Internal Server Error

Retry after delay, check service status

502/503

Service Unavailable

Check system status, retry with exponential backoff

Getting Help

Interactive Testing

Use the live API documentation to test endpoints and debug issues.

Community Support

Join the DestinE community forums for user discussions and shared solutions.

Examples Repository

Check the GitHub tutorials for working code examples.

Technical Support

Contact DestinE technical support for account-specific issues and bug reports.

Before Asking for Help

  1. Check this FAQ and error messages carefully

  2. Test with the interactive API documentation

  3. Try the minimal working examples from tutorials

  4. Include specific error messages and request details when reporting issues