# 即时重置配额

`POST` `/api/tokenBudget/resetQuotaUsage`

立即将指定身份主体某个配额账户的主额度本期已用量清零，并记录一条重置流水，用于周期内需要立刻恢复额度的场景。不传请求体或不传 scopeAgentId 时重置全局账户；传入共享配额的一组智能体中任意一个智能体的ID时，只重置这组智能体共享的智能体组账户，其他账户不受影响。仅清零主额度：加油包剩余额度不受影响，账户绑定关系与策略配置也不改变，后续周期重置照常触发。已用量为 0 时幂等返回成功。所查账户尚未绑定配额策略时返回 400；账户所绑策略未分配给当前应用时返回 403。本接口仅支持通过API调用。

## 请求参数

### 请求头参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Principal-Id | integer | 否 | 身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。 |

### 请求体（JSON）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| scopeAgentId | integer | 否 | 共享配额的一组智能体中任意一个智能体的ID，选填。不传或 0 表示重置主体的全局账户；传入时按该智能体所属智能体组定位到对应账户并只重置该账户，全局账户与其他组账户不受影响 |

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 400

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 500

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |