Error Response Format
All errors return a JSON response with a detail field explaining the error.
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"detail": "Error description here"
}400
Bad Request
The request was invalid or malformed.
Common Causes
- Invalid query parameters
- Malformed JSON body
- Missing required fields
Example Response
{
"detail": "Invalid date format. Use YYYY-MM-DD."
}401
Unauthorized
Authentication failed or was not provided.
Common Causes
- Missing X-API-Key header
- Invalid API key
- Revoked API key
Example Response
{
"detail": "Invalid or missing API key."
}403
Forbidden
You don't have permission to access this resource.
Common Causes
- Feature not available on your plan
- IP address not whitelisted
- API key expired
Example Response
{
"detail": "This feature requires a Pro or Business plan."
}404
Not Found
The requested resource doesn't exist.
Common Causes
- Invalid application ID
- Invalid council code
- Resource was deleted
Example Response
{
"detail": "Application not found."
}422
Validation Error
The request body failed validation.
Common Causes
- Invalid field values
- Type mismatches
- Constraint violations
Example Response
{
"detail": [
{
"loc": ["body", "url"],
"msg": "Invalid URL format",
"type": "value_error.url"
}
]
}429
Too Many Requests
You've exceeded your rate limit.
Common Causes
- Daily request limit exceeded
- Per-second rate limit exceeded
Example Response
{
"detail": "Rate limit exceeded. Retry after 60 seconds."
}500
Internal Server Error
Something went wrong on our end.
Common Causes
- Temporary server issue
- Database error
Example Response
{
"detail": "An unexpected error occurred. Please try again."
}503
Service Unavailable
The service is temporarily unavailable.
Common Causes
- Scheduled maintenance
- High traffic
Example Response
{
"detail": "Service temporarily unavailable. Please try again later."
}Best Practices for Error Handling
1.
Always check the status code before parsing the response body.
2.
Implement exponential backoff for 429 and 5xx errors.
3.
Log error details for debugging, but don't expose them to end users.
4.
Handle validation errors by parsing the loc field to identify which field failed.
Example Error Handler (Python)
import requests
import time
def make_request(url, headers, max_retries=3):
for attempt in range(max_retries):
response = requests.get(url, headers=headers)
if response.status_code == 200:
return response.json()
if response.status_code == 429:
# Rate limited - wait and retry
wait_time = 2 ** attempt # Exponential backoff
time.sleep(wait_time)
continue
if response.status_code >= 500:
# Server error - retry with backoff
time.sleep(2 ** attempt)
continue
# Client error - don't retry
error = response.json()
raise Exception(f"API Error: {error['detail']}")
raise Exception("Max retries exceeded")