> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nonce.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 请求与响应

> 了解资源路径、请求参数、分页和错误格式。

Public API v2 的基础地址为 `https://api.nonce.app/public-api/v2`。工作区资源的路径包含 `workspace_id`，矿场资源还包含 `farm_id`。这些 ID 来自 API 响应，与显示名称和 slug 不同。

## 请求参数

简单列表查询使用 URL 查询参数。结构化搜索使用 POST 提交 JSON 请求体，并设置 `Content-Type: application/json`；使用 POST 的接口也可能只读取数据。

例如，[Search Miners](/api-reference/v2/miners/search-miners) 可以通过以下请求体查询在线矿机：

```json theme={null}
{
  "status": { "eq": "online" },
  "page": 1,
  "page_size": 20
}
```

各接口支持的筛选条件和默认值不同，具体以对应的接口参考为准。

## 成功响应

响应包含 `success`、`data` 和 `error`。请求成功时，`success` 为 `true`，`error` 为 `null`；`data` 是对象还是数组，由接口定义决定。

分页列表还包含 `pagination`。空列表仍是成功响应：

```json theme={null}
{
  "success": true,
  "data": [],
  "pagination": {
    "total": 0,
    "page": 1,
    "page_size": 20,
    "total_pages": 0
  },
  "error": null
}
```

支持分页的列表和搜索接口中，`page` 默认为 1，`page_size` 默认为 20，每页最多 10,000 条。当 `page < total_pages` 时，继续请求下一页。部分接口不使用分页：`ListWorkspaces` 返回完整数组，历史指标查询则使用时间范围。

## 错误响应

API 错误响应中，`success` 为 `false`，`data` 为 `null`，`error` 包含 `code` 和 `message`。例如，矿场不存在或不在可访问范围内时，可能返回：

```json theme={null}
{
  "success": false,
  "data": null,
  "error": {
    "code": "FARM_NOT_FOUND",
    "message": "Farm not found"
  }
}
```

参数校验错误可能通过 `error.details.field_errors` 列出无效字段。联系支持团队时，应提供接口和请求时间；响应中若包含 `error.traceId`，也应一并提供。请勿附带凭据。

400 响应表示需要修正请求参数。其他访问错误见[认证与访问权限](/zh/api-guide/v2/authentication#访问错误)，重试建议见[速率限制与重试](/zh/api-guide/v2/rate-limits)。

## 时间、单位与空值

时间戳字段使用接口定义的 ISO 8601 格式。除非字段另有说明，算力单位为 H/s，功率为 W，能效为 J/TH。指标值为 `null` 表示数据缺失，不应按零处理。