Error Handling
Understanding API error responses and how to handle them effectively in your applications.
Overview
The Grid Status 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
200
Request succeeded
Client Error Codes (4xx)
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)
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.
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
403 Forbidden
Cause: Your subscription doesn't include access to the requested resource or feature.
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:
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
422 Unprocessable Entity - Query Timeout
Cause: The query took too long to execute and was cancelled.
Solutions:
429 Too Many Requests
Cause: You've exceeded rate limits or monthly usage limits.
Rate limit exceeded:
Monthly limit exceeded:
Solutions:
Implement exponential backoff
Check usage before large queries
Upgrade your plan if you consistently hit limits.
400 Bad Request
Cause: Invalid parameter values or missing required parameters.
Invalid column:
Invalid filter type:
Invalid resample frequency:
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
Related Documentation
Utility Endpoints - Monitor your usage to avoid limits
Advanced Query Features - Valid parameter values
Best Practices - Optimize queries to avoid timeouts
Last updated
Was this helpful?

