Errors

Error responses

All errors follow a consistent format:

1
{
2
  "detail": [
3
    {
4
      "type": "error",
5
      "msg": "description of what went wrong"
6
    }
7
  ]
8
}

HTTP status codes

Response compression

All responses over 1,000 bytes are automatically compressed with gzip. Make sure your HTTP client sends the Accept-Encoding: gzip header to benefit from reduced transfer sizes.

Best practices

• Cache responses when possible. Forecasts are typically updated every 1–6 hours depending on the metric.
• Use the header method (X-API-Key) for authentication to keep keys out of server access logs.
• Request specific targets — use the id parameter to fetch individual regions or plants when you don’t need all of them.
• Handle 422 gracefully — not all ISOs have data for all metrics or time ranges. Check the response before parsing.
• Handle 429s with backoff — implement exponential backoff in production applications rather than fixed-interval retries.
• Use the summary endpoint — if you need multiple metrics for a single ISO, GET /region/{iso}/summary returns everything in one call instead of multiple requests.