Documentation Index
Fetch the complete documentation index at: https://powersignals.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
Error Handling
The Power Signals API uses standard HTTP status codes and returns structured error responses.
All errors follow a consistent structure:
{
"error": "error_code",
"detail": "Human-readable description of what went wrong."
}
Status Codes
| Code | Meaning | When |
|---|
200 | Success | Request processed successfully |
400 | Bad Request | Invalid parameters (missing/malformed dates, unsupported interval) |
401 | Unauthorized | Missing or invalid API key |
403 | Forbidden | Key doesn’t have access to this resource |
404 | Not Found | Endpoint doesn’t exist |
429 | Too Many Requests | Rate limit exceeded |
500 | Internal Server Error | Something went wrong on our side |
Common Errors
Missing Parameters
{
"error": "missing_params",
"detail": "start and end datetime are required ISO-8601"
}
start and end query parameters in ISO-8601 format.
Invalid DateTime
{
"error": "invalid_datetime",
"detail": "start/end datetimes must be ISO-8601 datetimes"
}
2026-01-01T00:00:00Z or 2026-01-01T00:00:00+02:00.
Unsupported Interval
{
"error": "unsupported_interval",
"detail": "interval=5m not supported. Supported: ['1d', '1h']"
}
Bad Time Range
{
"error": "bad_request",
"detail": "start datetime must be < end datetime"
}
start parameter is before your end parameter.
Authentication Failure
{
"detail": "Authentication credentials were not provided."
}
X-API-KEY header in your request.
Data Delay Responses
If upstream data feeds (Eskom, SAPP) are delayed, the API will not return stale data. Instead, you’ll receive a response indicating the delay:
{
"meta": {
"dataset": "grid.system_state",
"data_delay": true,
"last_available": "2026-01-01T14:00:00Z",
"expected_by": "2026-01-01T15:30:00Z"
},
"data": []
}
Handling Errors in Code
import requests
response = requests.get(
"https://api.powersignals.co.za/api/v1/grid/system-state",
headers={"X-API-KEY": "your_key"},
params={"start": "2026-01-01T00:00:00Z", "end": "2026-01-02T00:00:00Z"},
)
if response.status_code == 200:
data = response.json()
elif response.status_code == 429:
retry_after = int(response.headers.get("Retry-After", 60))
print(f"Rate limited. Retry in {retry_after}s")
elif response.status_code == 400:
error = response.json()
print(f"Bad request: {error['detail']}")
elif response.status_code == 401:
print("Check your API key")
else:
print(f"Unexpected error: {response.status_code}")
