Error Handling

Understanding API error responses and how to handle them effectively in your applications.

Overview

The GridStatus API uses standard HTTP status codes to indicate the success or failure of requests. Error responses include a JSON body with details about what went wrong.

Error Response Format

All error responses follow this structure:

{
    "detail": "Human-readable error message describing what went wrong."
}

HTTP Status Codes

Success Codes

Code	Description
200	Request succeeded

Client Error Codes (4xx)

Code	Name	Description
400	Bad Request	Invalid parameters or malformed request
401	Unauthorized	Missing or invalid API key
403	Forbidden	Valid API key but insufficient permissions
404	Not Found	Resource (dataset, column, etc.) not found
422	Unprocessable Entity	Query timeout or validation error
429	Too Many Requests	Rate limit or usage limit exceeded

Server Error Codes (5xx)

Code	Name	Description
500	Internal Server Error	Unexpected server error
502	Bad Gateway	Upstream service unavailable
503	Service Unavailable	Server temporarily unavailable
504	Gateway Timeout	Request took too long

---

Common Errors and Solutions

401 Unauthorized

Cause: Missing or invalid API key.

{
    "detail": "API key is required."
}

Solutions:

• Verify your API key is correct

• Check that the API key is being passed correctly (header or query parameter)

• Ensure the API key hasn't been revoked

Shell

# Correct: API key as query parameter
curl "https://api.gridstatus.io/v1/datasets?api_key=YOUR_API_KEY"

# Correct: API key as header
curl -H "x-api-key: YOUR_API_KEY" "https://api.gridstatus.io/v1/datasets"

Python

---

403 Forbidden

Cause: Your subscription doesn't include access to the requested resource or feature.

{
    "detail": "Access to this dataset requires a paid subscription."
}

Common scenarios:

• Accessing a premium dataset on a free plan

• Using resampling without a paid subscription

• Accessing audit data without proper entitlements

Solutions:

• Upgrade your subscription plan

• Check which datasets are available on your plan

• Contact support if you believe you should have access

---

404 Not Found

Cause: The requested resource doesn't exist.

Dataset not found:

{
    "detail": "Dataset invalid_dataset_id not found."
}

Column not found:

{
    "detail": "Column not found."
}

Solutions:

• Verify the dataset ID is spelled correctly

• Use the list datasets endpoint to see available datasets

• Check that the column name exists using the dataset metadata endpoint

Shell

# List available datasets
curl "https://api.gridstatus.io/v1/datasets?api_key=YOUR_API_KEY" | jq '.data[].id'

# Check columns in a dataset
curl "https://api.gridstatus.io/v1/datasets/ercot_fuel_mix?api_key=YOUR_API_KEY" | jq '.all_columns[].name'

Python

---

422 Unprocessable Entity - Query Timeout

Cause: The query took too long to execute and was cancelled.

{
    "detail": "Query timed out. The following may allow the query to complete within the timeout: Reduce the time range of the query. Remove resampling. Use '=' instead of other comparison operators in filters. Set a limit on the number of rows returned. If none of these options work for you our Snowflake offering may meet your needs. Please contact us at [email protected] for more information."
}

Solutions:

1

Reduce time range

Example: Instead of querying all locations, filter to the specific location you need.

Shell

curl "https://api.gridstatus.io/v1/datasets/caiso_lmp_real_time_5_min/query?\
start_time=2026-01-01&\
end_time=2026-01-02&\
filter_column=location&\
filter_value=TH_SP15_GEN-APND&\
api_key=YOUR_API_KEY"

2

Add filters

Filter to specific locations instead of all locations.

Shell

curl "https://api.gridstatus.io/v1/datasets/ercot_lmp_by_settlement_point/query?\
start_time=2026-01-01&\
end_time=2026-01-02&\
filter_column=location&\
filter_value=HB_HOUSTON&\
api_key=YOUR_API_KEY"

3

Set a limit

Limit the number of rows returned.

Shell

curl "https://api.gridstatus.io/v1/datasets/pjm_lmp_real_time_5_min/query?\
start_time=2026-01-01&\
limit=100&\
api_key=YOUR_API_KEY"

4

Remove resampling

Server-side resampling can be expensive. Consider downloading raw data and resampling client-side.

---

429 Too Many Requests

Cause: You've exceeded rate limits or monthly usage limits.

Rate limit exceeded:

{
    "detail": "Rate limit exceeded. Try again in 60 seconds."
}

Monthly limit exceeded:

{
    "detail": "Monthly row limit exceeded. Limit resets on 2026-02-01."
}

Solutions:

• Implement exponential backoff

Python

# Configure the client with retry settings
retry_client = gs.GridStatusClient(
    api_key="YOUR_API_KEY",
    max_retries=5,      # Retry up to 5 times
    base_delay=2.0      # Start with 2 second delay
)

# Queries will automatically retry on 429 errors
df = retry_client.get_dataset("ercot_fuel_mix", start="2026-01-01", end="2026-01-02")

• Check usage before large queries

Python

usage = client.get_api_usage()

rows_used = usage['current_period_usage']['total_api_rows_returned']
rows_limit = usage['limits']['api_rows_returned_limit']
rows_remaining = rows_limit - rows_used

if rows_remaining < 10000:
    print("Warning: Low quota remaining!")

• Upgrade your plan if you consistently hit limits.

---

400 Bad Request

Cause: Invalid parameter values or missing required parameters.

Invalid column:

{
    "detail": "Column invalid_column not found in dataset. Possible columns: ['interval_start_utc', 'location', 'lmp']."
}

Invalid filter type:

{
    "detail": "Invalid type for filter_value, expected <class 'float'>."
}

Invalid resample frequency:

{
    "detail": "Invalid resample_frequency: '2h'. Must be one of: 5min, 15min, 30min, 1h, 1d, 1w, 1M."
}

Solutions:

• Check the error message for valid options

• Use the dataset metadata endpoint to verify column names

• Review the query parameters documentation

---

Error Handling Best Practices

1

Use Try/Except with the Client

Python

try:
    df = client.get_dataset("ercot_fuel_mix", limit=10)
    print(f"Success: {len(df)} rows")
except Exception as e:
    print(f"Error: {e}")

2

Implement Retry Logic

Python

# Configure the client with built-in retry logic
retry_client = gs.GridStatusClient(
    api_key="YOUR_API_KEY",
    max_retries=3,       # Number of retries
    base_delay=2.0,      # Initial delay in seconds
    exponential_base=2   # Multiply delay by this each retry
)

# All queries will automatically retry on transient errors (429, 500, 502, 503, 504)
df = retry_client.get_dataset("ercot_fuel_mix", limit=10)

3

Log Errors for Debugging

Python

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def query_with_logging(dataset: str, **kwargs) -> pd.DataFrame | None:
    try:
        df = client.get_dataset(dataset, **kwargs)
        logger.info(f"Query successful: {dataset}, {len(df)} rows returned")
        return df
    except Exception as e:
        logger.error(f"Query failed: {dataset}\nParams: {kwargs}\nError: {e}")
        return None

# Usage
df = query_with_logging("ercot_fuel_mix", start="2026-01-01", end="2026-01-02")

4

Handle Pagination Automatically

Python

# The client handles pagination automatically

# Just specify your query parameters and it fetches all pages
df = client.get_dataset(
    "ercot_fuel_mix",
    start="2026-01-01",
    end="2026-01-08"  # Large date range - client paginates automatically
)

print(f"Retrieved {len(df)} total rows across all pages")

Related Documentation

• Utility Endpoints - Monitor your usage to avoid limits

• Advanced Query Features - Valid parameter values

• Best Practices - Optimize queries to avoid timeouts