# Error Handling

All errors follow the standard response envelope with `status: "ERROR"`.

```json
{
  "status": "ERROR",
  "request_id": "cm_abc123...",
  "error": {
    "code": "error_code",
    "message": "Human-readable description."
  }
}
```

## Error codes

| HTTP Status | Code | Description |
|------------|------|-------------|
| 400 | `bad_request` | Missing or invalid query parameters. |
| 400 | `invalid_page_token` | The `page` parameter is invalid or expired. Repeat the list request without `page`, then follow each `next_url` the API returns. |
| 401 | `unauthorized` | Missing or invalid API key. |
| 403 | `forbidden` | Your plan does not include this endpoint. |
| 403 | `lookback_exceeded` | A date or timestamp parameter falls outside your plan's historical lookback window (3 years for Free, 7 years for Developer). Upgrade your plan or adjust the date range. |
| 404 | `not_found` | The requested resource does not exist. |
| 429 | `rate_limit_exceeded` | You have exceeded your plan's request limit. |