> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.isoview.io/llms.txt.
> For full documentation content, see https://docs.isoview.io/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.isoview.io/_mcp/server.

# Errors

## Error responses

All errors follow a consistent format:

```json
{
  "detail": [
    {
      "type": "error",
      "msg": "description of what went wrong"
    }
  ]
}
```

### HTTP status codes

| Code  | Meaning                                                                                                              |
| ----- | -------------------------------------------------------------------------------------------------------------------- |
| `200` | Success                                                                                                              |
| `401` | Missing or invalid API key                                                                                           |
| `403` | Your subscription does not include access to this ISO or tier                                                        |
| `404` | Endpoint not found                                                                                                   |
| `422` | Invalid parameters — e.g., unknown region ID, invalid date range, or no data available for the requested combination |
| `429` | Rate limit exceeded                                                                                                  |
| `500` | Internal server error — contact support if persistent                                                                |

A `422` response can also mean no data is available for the requested target or time range. This is common when querying newly added regions or very recent time windows before the forecast has been generated.

## 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.